Pull external data into bots via APIs

Automatically populate your bots with data from third-party applications, datasets, and more using Josef's inbound API functionality.

If you're unfamiliar with APIs, think of them as handy tools that allow Josef to retrieve information from external systems. The API can collect data and then push it into your bot via Josef variables. These API variables can then feature in message text, responses, bot logic, and more. 

There is a whole range of systems that can currently push data to Josef. A few examples include Airtable, ABN Lookup Australia, Companies House UK, Google Sheets, and more. 

• Note: If you're looking to push information from Josef into third-party applications (e.g. Slack, SharePoint, Xakia, etc.), check out our other outbound integrations.  
• Feel free to contact us at support@joseflegal.com to confirm whether or not your system is compatible with Josef. 

In this article, you'll learn how to start sending data directly to your bot(s) and which APIs Josef supports.

• Overview
  • What you'll need
• Select a compatible system
  
  • Clarify with IT team
  • Determine compatibility 
  • Locate API endpoint(s)
  • Guidance
• Build an API-ready bot
  • API request response type
  • API request variable
• Test and troubleshoot
  • Checklist
  • Test
  • Troubleshoot
• Glossary

[Image: API request variables hosted in the Variables library in Flowchart]

Overview 

APIs enable builders to create bots that pull external data (e.g. information located in online spreadsheets on Airtable or Google Sheets, etc.) into bot messages and responses.

This data can then populate variables which, in turn, can feature in documents, and notifications and can also determine bot logic.

What you'll need

While this article should give you all the information you need to complete the setup, you may require assistance from your IT or web development teams.

At a high level, the setup will require the following:

1. Access to Josef's integrations as part of your organization's license
   
   • Note: Feel free to contact us at support@joseflegal.com to confirm whether you have access!
2. One or more Josef bots
   • Where the data will be sent and displayed to end-users.
3. A compatible third-party system
   • This is the data source. (Learn how to identify a compatible system below.)
4. Knowledge of JSON
   • The programming language Josef uses to connect with third-party systems.
   • Note: If you're unfamiliar with JSON and want to learn more, visit this article. Alternatively, contact your IT team to help set up the integration using the information below. If you get stuck, feel free to contact us at support@joseflegal.com.
5. API Access token(s) (optional)
   • If you're looking to pull information from a private Salesforce dataset or SharePoint list, for example, you'll likely need to generate API access tokens. These will grant Josef access to the relevant information stored in your third-party system.
   • Learn more about access tokens.

Select a compatible system

First up, you'll need to decide which system you want to connect with Josef. 

In order to be compatible with Josef, the system will need to meet the following technical requirements:

1. Accepts API requests (e.g. a public REST API)
2. Returns API requests with data in JSON format
3. Uses an API key or Oauth 2.0 when authentication is required to access the data

Read on to learn how you can determine whether the relevant system is compatible.

Clarify with IT team

APIs can get technical pretty quickly, so if you’re unsure if your proposed system supports the above requirements, ask your IT team or the third-party system's Support team for guidance. 

Alternatively, if you get stuck feel free to introduce us at support@joseflegal.com and we’ll help follow up.

Determine compatibility

For those of you trying to figure out the compatibility of the system, feel free to use the below example as a guide of what to check. 

Let's take the spreadsheet database platform Airtable as an example. In this case, we'd like to pull data from one of its spreadsheets.

[Image: An example of an Airtable spreadsheet]

 

By reviewing Airtable's integration documentation, we can confirm the platform: 

1. Accepts API requests using a public REST API
   • "The Airtable API can be used to integrate your data in Airtable with any external system. The API closely follows REST semantics". - Airtable
2. Supports API return requests in the JSON format
   •  "...uses JSON to encode objects". - Airtable
3. Uses an API key that'll enable Josef to access spreadsheet data
   • "Airtable API keys allow you to use Airtable's Web API to create, fetch, update, and delete records in the bases you have access to in Airtable." - Airtable

With the above confirmed, we can continue with our setup. 

[Image: Airtable's interactive API documentation detailing how to "Retrieve a record"]

Locate API endpoint(s)

Next, you'll need to locate the API endpoint(s). 

These are URLs that serve as touch points that, in this instance, enable us to establish contact between a Josef bot and the data stored in an Airtable spreadsheet. 

Once we locate the endpoint specific to our Airtable spreadsheet, we'll be on our way to pulling data into our Josef bot.

Guidance

For general guidance on obtaining this information from your third-party system, follow these general steps.

1. Access the system's Help centre, API resources or developer portals. 
   • Hint: Similar to Josef, these are likely accessible via the app itself. Otherwise, consider searching for "[system] API documentation" via Google. 
2. Consider what data you'd like to retrieve and search the relevant chapters/articles on this data.
   • Hint: The relevant resource will likely include terms like "GET", “requests” and  "endpoint", etc. They may also feature example passages of JSON code. These passage examples will serve as a base from which you can write your specific API endpoint. 
   • Example resources: Google Sheets, SharePoint and Xakia. 
3. Obtain the API endpoint.
   • Hint: In some platforms, this may be accessible via the app itself (e.g. via Admin, Developer or Settings tabs). In other cases, you may need to use information in help articles (i.e. examples of endpoints) in conjunction with information accessible via the app itself. 
4. Ask for help, if needed!
   • If you get stuck, contact the third-party platform's Support service. They'll likely direct you to the correct documentation and relevant information within their app. Otherwise, contact us at support@joseflegal.com and we'll help follow up. 

Example: Airtable

By consulting Airtable's interactive API resources, we have been able to collect both the API endpoint and API key required to connect with Josef.

1. API endpoint e.g.

   https://api.airtable.com/v0/appXY6eQWkq9TDYB2/Procurement%20DB/recuJq5Z6agFxwcd

2. API key e.g.

   abcdef12345

 

Important!

Once at this stage, note down the endpoint(s) that will retrieve the relevant data. You’ll need them to build an API-ready bot.

Build an API-ready bot

Now it's time to build your bot so that it can receive the data via the API.

In Josef, bots can retrieve data in two ways.

1. Via an API request response type
   • Allows builders to pull information directly into bot response fields (e.g. an email address, phone number, etc.). This means that responses can be pre-populated, requiring less work for the builder and end-user. An end-user can simply confirm the pre-populated response is correct, or input a new one if required. 
   • Note: The user must reach the relevant bot message in order for the bot to retrieve this data. 
2. Via an API request variable (stored in your bot's Variables library)
   • Allows builders to create standalone variables that in some cases do not require any user input in order to be populated. These can then feature across bots helping reduce time spent inputting repetitive information.
   • Note: Unlike above, these variables are often populated with data as soon as the bot interaction commences, retrieving it automatically.

These variables can then be inserted into message text, notifications, documents, or calculations like any normal variable. 

API request response type

[Image: The Add message sidebar open in Flowchart featuring an API request response]

Overview

This allows builders to push data (pulled from an external system) directly into bot response fields, including

• Text
• Single choice
  • SC - text
    
  • SC - number
  • SC - date
  • SC - currency
  • SC - percentage
• Multiple choice
• Full name
• Email
• Phone number
• Address
• Number
• Date
• Currency
• Percentage
  

This means the user won't always have to input an email response, for example. It'll be automatically populated for them!

Setup

To start, create a message and select API request response type in the Edit message sidebar. 

Follow the prompts to enter the following.

• API URL
  • This is the API endpoint from which you'd like to retrieve data. 
  • (optional) To ensure the API collects the most relevant information (e.g. a contact's email), builders can add end-user responses (i.e. a contact's name) as API parameters at the end of the API URL. The API can then collect the email associated with a contact's name from the external database and pull it back into Josef.  
    • What's this?

• API response type 
  • In this field, confirm the type of data being retrieved from your system, (e.g. an email address, full name, or multiple-choice options, etc.).
  • Reminder: Any data pulled into the responses will need to meet the formatting requirements of whatever response type is being populated. Learn the requirements here. 

• Advanced settings (optional)
  • Add a Request header to add supplemental header data to your request. 
    • What's this?
  • Add a Response path to determine what specific part of the returned data will populate your bot response(s). 
    • What's this?

• API Authorization token (optional)
  • If your third-party system requires that you create an access token to grant Josef access to a specific dataset, you will need to have:
    • Created and connected the token, then
    • Select the relevant token via the dropdown in the Edit message sidebar. 
  • Learn about creating and managing access tokens.

 

API request variable

[Image: Builder creating a standalone API request variable in the Variables library in Flowchart]

Overview

Choose this option to push data from your third-party system into API request variables that require no end-user input. Such data is often pushed into your bot the moment an interaction commences.

An example could be an invoice or case number (pulled from an external database) which can then be inserted into messages, notifications, documents and calculations, like any other variable.

Setup

To create a standalone API request variable:

1. In either List view or Flowchart, open the Variables library; and
2. Click Create new variable. 
3. Select API request from the Variable type dropdown menu. 

Next, follow the prompts to enter the following.

• Variable name
  • • The name of the variable as it appears in the bot-building environment. The contents of the variable will be determined by the information retrieved by the API.

• API URL
  • • This is the API endpoint from which you want to retrieve data. 
    • (Optional) To make the API request more specific, builders can also add end-user responses as API parameters in the API URL. 
      • What's an API parameter?

• Confirm your API response type.
  • Here, confirm the kind of data being retrieved from your system (e.g. an email address, full name etc.). 
    • This will determine the functionality of the variable within your bot. 
    • Hint: Recommended response types include Text, Full name, Email, Phone number, Address, Number, Date, Currency, and Percentage. Alternatively, select Rich text to pull information into bot messages featuring a range of HTML formatting features (e.g. bold, italics, underline, line breaks, etc.).

• Advanced settings (optional) 
  • Add a Request header to add supplemental header data to your request.
    • What's this?
  • Add a Response path to determine what specific part of the returned data will populate your bot response(s). 
    • What's this?

• API Authorization token (optional) 
  • • If your third-party system requires that you create an access token to grant Josef access to a specific dataset, you will need to have
      • Created and connected the token, then
      • Select the relevant token via the dropdown in the Edit message sidebar.
    • Learn about creating and managing access tokens.

Test and troubleshoot

Checklist

You're nearly done! By this point, you will have

1. Confirmed that your third-party system is compatible with Josef;
2. Built your bot logic;
3. Created the relevant API request response types and/or built standalone API request variables; and 
4. You will have inserted the variables into the relevant places in your bot (e.g. message text, notifications, documents, etc.)
5. Depending on the platform, you may have also created, connected and applied API access tokens. 

Now, let's check it all works!

Test

Testing can be performed in either Preview or Live mode. To avoid sending any unnecessary notifications, we'd recommend first testing in Preview. 

Click Preview in the bottom-left of your bot's building environment and test the bot flows as intended. 

Troubleshoot

If, when you interact with the bot, you (a) receive a "Stuck" alert in place of an API message, or (b) messages are missing information, review the contents of your API request and response variables. 

Here are some things you can check. 

1. Is the URL returning JSON data?
   • Why? This is the required programming language API URLs need to use in order to be compatible with Josef. 
2. Is the URL returning JSON data in the format required by the chosen API response type?  
   • For example, If you're looking to populate a Full name variable, the retrieved data must meet the response type's requirements of at least two words separated by a space. See further response requirements here. 
3. If you’ve added response headers, double-check that the contents are correct.
4. If you’ve specified a response path in your API URL, ensure it has the correct syntax. 

Once you've reviewed, updated and confirmed your bot's working as expected, you're good to go!

Glossary

APIs can get pretty technical pretty quickly. To help you get set up, here are some introductory definitions of some of the terms dotted throughout the article.

API endpoint

These URLs serve as touch points that enable builders to establish contact between a Josef bot and an external database, such as an Airtable spreadsheet. 

In the case of an Airtable spreadsheet, you can think of it as the spreadsheet's API request address. Or in simpler terms, it functions much like a building's address (e.g. Empire State Building, 20 W 34th St., New York, NY 10001, United States).

API key

This can determine how and whether the API is granted access to the API endpoint. As mentioned, if a system's API requires authentication to access its data, you'll need to use an API key. 

Using Airtable, for example, it's what allows builders to "use Airtable's Web API to create, fetch, update, and delete records in the bases you have access to in Airtable". Think of it like a key to a door!

API parameter

While APIs can grant you access to a whole dataset (e.g. a whole spreadsheet), an API parameter can help narrow the API's scope to retrieve only the most relevant piece of information. 

On Airtable, this could be a specific column or row in a given spreadsheet. For example, if you think of the API endpoint as a street address, the API parameter is like the level or floor of the building. 

Note: Not all API systems support parameters, so be sure to check your third-party platform's API documentation to confirm.

API response path

With the ability to work in conjunction with parameters, response paths provide APIs with further directions to a specific location in an API request. 

The parameter provides the initial guidance, while the response path can direct the API to even more specific, related data. 

In an Airtable spreadsheet, this could be a cell located on the same row as that identified by the parameter. The parameter could direct the API to a contact's name in Row 1 Column 1, while the response path would direct the API to the contact's email located in Row 1 Column 2. 

In other words, if you think of the API endpoint as a street address, the API response path is like instructions to a particular room in that building.

 

Example

In the image below we have the contents of an API endpoint on the left and the Josef Dashboard on the right.

In the Dashboard (on the right), we have specified the Response path as "fields.Owner". Think of "fields" as one folder, and  "Owner" as the subfolder within.

"Owner" contains our desired piece of information, "H H". Once identified, the API can  then pull "H H" straight into a Josef bot, specifically as a Full name variable.

[Image: API request featuring the "fields.Owner" response path (on the left) and the Josef Variables library (on the right)]

API request header

The function of request headers varies from system to system, but common use cases relate to the API's language (e.g. JSON) and they can also provide spaces to store API keys. As such, they can play an essential role since all API requests made through Josef must be in JSON format.

Note: Not all systems support request headers, and their function ranges according to a system's API, so be sure to check your third-party platform's API documentation to confirm.

To learn more about API request headers, visit this Mozilla article.

JSON

This is the programming language Josef uses to connect with third-party systems via APIs.

Note: If you're unfamiliar with JSON and want to learn more, visit this article. Alternatively, contact your IT team to help set up the integration or if you get stuck, feel free to contact us at support@joseflegal.com.

 

Happy building!