Airtable

Are you looking to pull data from Airtable into your Josef bots? With Josef's inbound API functionality, you can do just that!

What follows should be read alongside our article on integrating with third-party applications.

Note: The information below details just one way of integrating with Airtable. It does not represent the full breadth of functionality available. If you'd like to explore other ways of integrating with Airtable, we recommend checking out our API guidance (linked above) alongside Airtable's own API documentation.

• Overview
• What you'll need
• Setup
  • Retrieve personal access token
• Connecting Airtable
  • Example: populate a standalone API request variable 
    1. 1. Access Airtable's API documentation
       2. Initial setup Determine the API request
       3. Determine the API request
       4. Test
  • Alternative: create an API request response type  
• Help

Overview

By integrating Josef bots with Airtable, builders can retrieve any data hosted in an Airtable base (i.e. a spreadsheet), such as a name, email address, phone number, etc. This can then pre-populate:

1. API request response types; and/or
   • A response type on Josef that allows builders to pull information directly into bot response fields (e.g. an email address, phone number, etc.). Once populated, an end-user can simply confirm the response is correct in the bot UI, or input a new one if required. 
2. Standalone API request variables
   • A Josef variable that allows builders to create standalone variables that in some cases do not require any end-user input in order to be populated. These can then feature across bots helping reduce time spent inputting repetitive information.

Once retrieved, this information can also be inserted elsewhere in bots, including in bot message text, notifications, automated documents and/or calculations like any normal variable. 

What you'll need

To integrate with Airtable, you'll first need two things. 

1. an Airtable account; and
2. an Airtable base (i.e. spreadsheet) that hosts all the relevant information you'd like to pull into your Josef bot(s). 

[Image: an Airtable base example entitled "Organisation's base" featuring the table "Table 1"]

Setup

Retrieve personal access token

Next, you'll need to retrieve the Airtable personal access token that will grant Josef access to the base. To learn how to retrieve this, visit this Airtable article.

[Image: A saved personal access token featuring a Name, Scope and Access]

At a high level, it involves the following.

1. Open your Airtable base.
2. In the top right, click your account dropdown and select Developer hub.
3. This will open the Personal access tokens page. In the top left, click Create new token.
4. Once in Create personal access token, give your token a name of your choosing.  
5. Under Scopes, click Add a scope. 
6. To ensure Josef can retrieve the data from Airtable, click data.record: read from the Scope dropdown. 
7. Next, under Access, click Add a base. From the dropdown, select which workspace or base you'd like to retrieve data from.
   • Hint: You can choose from all your data hosted Airtable or just one base. 
8. Once complete, click Create token.
9. A popup will appear containing your personal access token. Copy and paste this somewhere safe and do not share it with anyone.
10. Click Done.

Connecting Airtable

Next, you’ll need to actually set up your API requests by connecting Airtable. 

There are near-infinite ways to integrate Josef with Airtable and they can't all be covered in one article, although we wish they could! 

For a comprehensive look at what API requests Airtable supports, see here; and for guidance on how to make the relevant API requests via Josef, see here. 

Be aware that this gets pretty complex pretty quickly, so to get started, feel free to check out the Example setup instructions below for more context, and/or jump straight to the Help section if you need more assistance.

Example: populate a standalone API request variable

Here's a quick run-through explaining how to pull Airtable data into a Josef standalone API request variable. 

1. Access Airtable's API documentation

Once you have your Airtable base set up and your Airtable personal access token to hand, you can then start retrieving the necessary API setup details. 

[Image: Airtable's API documentation featuring the relevant Workspace (Organisation's base) at the bottom of the introduction]

1. Go to airtable.com and open the relevant base (i.e. spreadsheet). 
2. A base populated with the relevant data (e.g. a contacts library) should appear. 
3. In a separate browser tab, open Airtable's API documentation.
4. In the documentation's Introduction tab, in the centre of the bottom of the page, select the relevant base from which you'd like to retrieve data.
5. Once this has loaded, click the name of the table in your base from the left-hand tab. 
   • Hint: This is located under Authentication.
6. Select Retrieve a record located below.

2. Initial setup via Airtable's API documentation

On the left panel, you'll find guidance on what it means to retrieve a record and the API requirements. In short, it enables us to pull data into Josef. 

[Image: the Retrieve a record tab in Airtable's API documentation with the curl tab on the right]

On the right, in the curl tab, you'll find information relating to an Example request (featuring the details required to send data from Airtable to Josef) and an Example response (featuring the contents of data available to send). 

For this example, we'll be gathering details under Example request and inserting them into Josef.

3. Determine the request

Part 1: Begin creating the variable 

Next, you'll need to open Josef in a separate browser tab to start setting up the API request. 

1. Open your Josef bot via the Dashboard. 
2. In either List view or Flowchart, open the Variables library via the panel on the right. 
3. Click Create variable.
4. Set the Variable type to API request.
5. Give the variable a name.
6. Assign the relevant API request response type. 
   • Hint: If you're pulling an address, assign it Address. If you're pulling a person's full name, assign it Full name, and so on. 
7. Return to the Airtable documentation and copy the URL located under Example request after "curl". 
   • Note: Only copy the URL. Do not copy the quotation marks on either side.
8. Return to Josef and paste the URL into the variable's URL field.

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

 

Part 2: Confirm API request authorisation

Next, open the Advanced settings dropdown in Josef's Create a new variable tab.  

1. In the key field, insert the first word listed under the API URL from Airtable's curl tab. 
   • Hint: This will most likely be the word Authorization.
2. In the value field, copy the word Bearer, add a space and then paste the personal access token collected earlier.

By doing the above, we are including the personal access token to Josef's API request made to Airtable. This is required to ensure Airtable knows the request is being sent from someone who has the personal access token. 

Now let's ensure it pulls out the relevant information by populating the Response path. 

[Image: Advanced settings dropdown featuring key, value and Response path fields]

1. Return to the API documentation and review the contents of the Example response. 
   • This contains all the information can you pull into Josef. Now let's choose what specifically. 
   • Note: Determining this may require knowledge of JSON, the programming knowledge Josef uses to make API requests. To learn more about JSON, visit this article. 
2. Under Example response, you may find records listed at the top. Each subsequent passage of text underneath contains all the information in each of your base's (i.e. spreadsheet's) rows (e.g. name, address, ABN, etc.). 
   • Note: the names of the fields will vary according to the names of your base's columns. In the image above, you'll see there is only Name and Address. 
3. If you're looking to retrieve an address from the first row in your base, the response path will look something like this: "records[0].fields.Address"
   • Note: "0" refers to the first row in your base, "fields" refers to all the columns in your base, and "Address" refers to the exact column name containing the address details. 
4. Once you've inputted the response path, click Create. 
   • The new variable will then be hosted in the Variables library under API request variables. 
5. You're nearly done!

[Image: the curl tab featuring Example request and Example response]

4. Test

It's time to ensure the API request works as expected. For best testing practices, see here. 

Once testing is complete, you can then insert this variable throughout your bot including in message text, notifications, automated documents, and/or calculations.

Alternative: create an API request response type. 

To push this data directly into a bot response, you'll need to follow the steps above, but instead of inputting the relevant API details into a standalone API request variable via the Variables library, you'll need to do so via API request response types created in bot messages. 

For information on how to create an API request response types, see here. 

Help

Together, the example instructions above, alongside Airtable's API documentation and our general API guidance should provide you with all you need to set up the integration, but if you get stuck, we recommend 

1. Reaching out to your IT or web development teams for help; and/or
2. Contacting Airtable's Support team.

Please also feel free to contact us at support@joseflegal.com and we'll help follow up.

 

Happy building!