---
title: Pull external data into bots via APIs
description: Automatically integrate third-party data into your Josef bots using APIs. Learn to set up, test, and troubleshoot for seamless data flow.
---

[Skip to content](https://help.joseflegal.com/pull-external-data-into-bots-via-apis#main-content)

<https://help.joseflegal.com/kb-tickets/new?hsLang=en>

[![Josef Logo](https://help.joseflegal.com/hs-fs/hubfs/josef-logo-4.png?width=120&height=40&name=josef-logo-4.png)](https://www.joseflegal.com)

Open main navigation

Close main navigation

- <https://help.joseflegal.com/kb-tickets/new>
- [Contact us](https://help.joseflegal.com/kb-tickets/new)

[Contact us](https://help.joseflegal.com/kb-tickets/new?hsLang=en)

 How can we help you?

- There are no suggestions because the search field is empty.

1. [Support](https://help.joseflegal.com/?hsLang=en)
2. [Josef No-Code Automation Platform](https://help.joseflegal.com/josef-no-code-automation-platform?hsLang=en)
3. [Integrations](https://help.joseflegal.com/josef-no-code-automation-platform?hsLang=en#integrations)

# 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](https://help.joseflegal.com/create-messages?hsLang=en), [responses](https://help.joseflegal.com/response-types?hsLang=en), bot logic, and more. 

There is a whole range of systems that can currently push data **to Josef**. A few examples include [Airtable](https://airtable.com/developers/web/api/introduction), [ABN Lookup Australia](https://abr.business.gov.au/Tools/WebServices), [Companies House UK](https://developer.company-information.service.gov.uk/overview), [Google Sheets](https://developers.google.com/sheets/api/guides/concepts), and more. 

- **Note:** If you're looking to push information **from Josef** into third-party applications (e.g. [Slack](https://help.joseflegal.com/slack?hsLang=en), [SharePoint](https://help.joseflegal.com/sharepoint?hsLang=en), [Xakia](https://help.joseflegal.com/xakia?hsLang=en), etc.), check out our other outbound [integrations](https://help.joseflegal.com/josef-no-code-automation-platform?hsLang=en#integrations).
- Feel free to contact us at [support@joseflegal.com](mailto: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**

![6332660663695](https://help.joseflegal.com/hs-fs/hubfs/Knowledge%20Base%20Import/6332660663695.png?width=688&height=347&name=6332660663695.png)

\[**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](https://help.joseflegal.com/creating-a-document-in-the-word-editor?hsLang=en), and [notifications](https://help.joseflegal.com/send-notification-emails?hsLang=en) 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](mailto:support@joseflegal.cm) 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](https://blogboard.io/blog/knowledge/jsonpath-python/). 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](mailto: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](https://help.joseflegal.com/managing-access-tokens?hsLang=en) 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](https://blogboard.io/blog/knowledge/jsonpath-python/)
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](mailto: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](https://airtable.com/) as an example. In this case, we'd like to pull data from one of its spreadsheets.

![6332660832783](https://help.joseflegal.com/hs-fs/hubfs/Knowledge%20Base%20Import/6332660832783.png?width=688&height=346&name=6332660832783.png)

\[**Image:** An example of an Airtable spreadsheet\]

 

By reviewing Airtable's [integration documentation](https://support.airtable.com/docs/public-rest-api), 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](https://airtable.com/developers/web/api/introduction)
2. **Supports API return requests** in the **JSON format** 
     - ...uses JSON to encode objects. - [Airtable](https://airtable.com/developers/web/api/introduction)
3. Uses an [**API key**](https://support.airtable.com/docs/creating-and-using-api-keys-and-access-tokens) 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](https://support.airtable.com/docs/creating-and-using-api-keys-and-access-tokens)

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

![6332674872207](https://help.joseflegal.com/hs-fs/hubfs/Knowledge%20Base%20Import/6332674872207.png?width=688&height=346&name=6332674872207.png)

\[**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](https://developers.google.com/sheets/api/guides/concepts), [SharePoint](https://learn.microsoft.com/en-us/sharepoint/dev/sp-add-ins/get-to-know-the-sharepoint-rest-service?tabs=csom) and [Xakia](https://xapi-au.xakiatech.com/apibrowser/index.html?urls.primaryName=Matters).
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](mailto: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](https://help.joseflegal.com/create-messages?hsLang=en), [notifications](https://help.joseflegal.com/send-notification-emails?hsLang=en), [documents,](https://help.joseflegal.com/creating-a-document-in-the-word-editor?hsLang=en) or [calculations](https://help.joseflegal.com/calculations-and-variables?hsLang=en) like any normal variable. 

#### **API request response type**

![6332660664847](https://help.joseflegal.com/hs-fs/hubfs/Knowledge%20Base%20Import/6332660664847.png?width=688&height=347&name=6332660664847.png)

\[**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](https://help.joseflegal.com/response-types?hsLang=en) 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](https://help.joseflegal.com/create-messages?hsLang=en) and select [**API request response type**](https://help.joseflegal.com/response-types?hsLang=en) 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?](https://help.joseflegal.com/pull-external-data-into-bots-via-apis#glossary)**

- **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](https://help.joseflegal.com/response-types?hsLang=en).

- **Advanced settings** (optional) 
    - Add a **Request header** to add supplemental header data to your request.  
          - [**What's this?**](https://help.joseflegal.com/pull-external-data-into-bots-via-apis#glossary)
    - Add a **Response path** to determine what specific part of the returned data will populate your bot response(s).  
          - [**What's this?**](https://help.joseflegal.com/pull-external-data-into-bots-via-apis#glossary)

- **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**](https://help.joseflegal.com/managing-access-tokens?hsLang=en) about creating and managing access tokens.

#### **API request variable**

![6332674871695](https://help.joseflegal.com/hs-fs/hubfs/Knowledge%20Base%20Import/6332674871695.png?width=688&height=346&name=6332674871695.png)

\[**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](https://help.joseflegal.com/calculations-and-variables?hsLang=en); 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?**](https://help.joseflegal.com/pull-external-data-into-bots-via-apis#glossary)

- 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**](https://help.joseflegal.com/response-types?hsLang=en) 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?**](https://help.joseflegal.com/pull-external-data-into-bots-via-apis#glossary)
    - Add a **Response path** to determine what specific part of the returned data will populate your bot response(s).  
          - [**What's this?**](https://help.joseflegal.com/pull-external-data-into-bots-via-apis#glossary)

- **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**](https://help.joseflegal.com/managing-access-tokens?hsLang=en) 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](https://help.joseflegal.com/managing-access-tokens?hsLang=en)**.

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](https://help.joseflegal.com/testing-a-bot?hsLang=en) 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](https://blogboard.io/blog/knowledge/jsonpath-python/)? 
     - **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](https://help.joseflegal.com/response-types?hsLang=en).
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](https://blogboard.io/blog/knowledge/jsonpath-python/).

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](https://support.airtable.com/docs/creating-and-using-api-keys-and-access-tokens), 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.

![6368838034703](https://help.joseflegal.com/hs-fs/hubfs/Knowledge%20Base%20Import/6368838034703.png?width=688&height=352&name=6368838034703.png)

\[**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](https://developer.mozilla.org/en-US/docs/Glossary/Request_header).

 

**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](https://blogboard.io/blog/knowledge/jsonpath-python/). 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](mailto:support@joseflegal.com).

 

Happy building!

- [Josef Q](https://help.joseflegal.com/josef-q?hsLang=en#main-content)

    - [Using tools](https://help.joseflegal.com/josef-q?hsLang=en#using-tools)
    - [Training tools](https://help.joseflegal.com/josef-q?hsLang=en#training-tools)
    - [Preparing a knowledge base](https://help.joseflegal.com/josef-q?hsLang=en#preparing-a-knowledge-base)
    - [Release note (Josef Q)](https://help.joseflegal.com/josef-q?hsLang=en#release-note-josef-q)
    - [Creating tools](https://help.joseflegal.com/josef-q?hsLang=en#creating-tools)
    - [Managing tools and accounts](https://help.joseflegal.com/josef-q?hsLang=en#managing-tools-and-accounts)
    - [Integrations](https://help.joseflegal.com/josef-q?hsLang=en#integrations)
    - [Resources](https://help.joseflegal.com/josef-q?hsLang=en#resources)
    - [Monitoring & maintaining tools](https://help.joseflegal.com/josef-q?hsLang=en#monitoring-maintaining-tools)
- [Josef No-Code Automation Platform](https://help.joseflegal.com/josef-no-code-automation-platform?hsLang=en#main-content)

    - [Building bots](https://help.joseflegal.com/josef-no-code-automation-platform?hsLang=en#building-bots)
    - [Integrations](https://help.joseflegal.com/josef-no-code-automation-platform?hsLang=en#integrations)
    - [Notifications and workflows](https://help.joseflegal.com/josef-no-code-automation-platform?hsLang=en#notifications-and-workflows)
    - [Document creation](https://help.joseflegal.com/josef-no-code-automation-platform?hsLang=en#document-creation)
    - [Managing bots](https://help.joseflegal.com/josef-no-code-automation-platform?hsLang=en#managing-bots)
    - [Testing, troubleshooting and editing](https://help.joseflegal.com/josef-no-code-automation-platform?hsLang=en#testing-troubleshooting-and-editing)
    - [Launching](https://help.joseflegal.com/josef-no-code-automation-platform?hsLang=en#launching)
    - [Single Sign-On](https://help.joseflegal.com/josef-no-code-automation-platform?hsLang=en#single-sign-on)
    - [FAQs](https://help.joseflegal.com/josef-no-code-automation-platform?hsLang=en#faqs)
    - [Getting started on Josef no-code](https://help.joseflegal.com/josef-no-code-automation-platform?hsLang=en#getting-started-on-josef-no-code)
    - [Release notes & FAQs for Josef no-code](https://help.joseflegal.com/josef-no-code-automation-platform?hsLang=en#release-notes-faqs-for-josef-no-code)
    - [Managing accounts](https://help.joseflegal.com/josef-no-code-automation-platform?hsLang=en#managing-accounts)
    - [Reporting](https://help.joseflegal.com/josef-no-code-automation-platform?hsLang=en#reporting)
    - [Formatting a bot](https://help.joseflegal.com/josef-no-code-automation-platform?hsLang=en#formatting-a-bot)

[![Chill listening crop-3](https://help.joseflegal.com/hs-fs/hubfs/Josef%20logo.png?width=72&height=24&name=Josef%20logo.png "Chill listening crop-3")](http://joseflegal.com)

[support@joseflegal.com](mailto:support@joseflegal.com) 

<https://twitter.com/joseflegal/> <https://www.linkedin.com/company/joseflegal/> [mailto:support@joseflegal.com](mailto:support@joseflegal.com)

Copyright © 2025, Josef Legal