# Airtable: find, add, update and delete records

> Connect Airtable to Avox with a personal access token so automations can find, add, update, add-or-update and delete records, add files and comments. Scopes, limits and what happens if Airtable fails.

Source: https://docs.theavoxai.com/connections/apps/airtable

Connect Airtable and an automation can save a Flow's answers as a record, keep one record per
customer, or look a record up and use its fields in a reply. You can also browse your tables and
records from inside Avox.

## What Avox can and cannot do with Airtable

- **Can:** list your bases, and show each table's fields, types and views.
- **Can:** find records (by a field's value, a filter formula, a view and a sort), and get one record.
- **Can:** add, update, and add-or-update records, delete records, add files to a record from a link,
  and read and add comments (when the token allows it).
- **Cannot:** change the structure of your bases (tables, fields, views).
- **Cannot:** fill fields Airtable works out itself, such as formula, rollup, lookup, count and
  created time ([AVX-3731](https://docs.theavoxai.com/error-codes/avx-3731)).
- **Cannot:** reach a base the token was not given.
- **One direction only:** Avox reads Airtable when a step or a page asks, so a change in Airtable
  never starts an automation.

A step works on one record at a time. **Add an Airtable record** always adds, so a customer who sends
a Flow twice gets two records. To keep one per customer, use **Add or update an Airtable record**.

## What you need before you start

- An Airtable account, bases where you can add and change records, and permission to make a
  personal access token. Nobody at Avox has to switch Airtable on, so it never says **Coming soon**.
- A plan on your Switchboard, which sets how many apps you can connect
  ([AVX-3683](https://docs.theavoxai.com/error-codes/avx-3683), [AVX-3706](https://docs.theavoxai.com/error-codes/avx-3706)).
- The permission **Manage connected apps** in Avox. Admins have it, and can give it to a Manager
  ([AVX-3707](https://docs.theavoxai.com/error-codes/avx-3707)).

## Make the token and connect

**1. Create a token in Airtable**

Open [airtable.com/create/tokens](https://airtable.com/create/tokens) and click **Create new
token**. Name it **Avox**.

**2. Add the scopes**

Add the scopes in the table below. The three required ones are needed to connect.

**3. Choose the bases**

Under **Access**, add the bases Avox may use, or a whole workspace. Avox cannot open any other base.

**4. Create and copy**

Click **Create token** and copy it. Airtable shows it only once.

**5. Connect in Avox**

Open **Apps** in the sidebar, pick **Airtable** and click **Connect**, then **Continue**. Paste the
token into **Personal access token**. If you like, fill **Default base ID** with the part of a
base's link that starts with `app`. Click **Connect**. Avox tries the token with Airtable first.

| Scope |  | What it lets Avox do |
| --- | --- | --- |
| data.records:read | Required | See the records in your bases |
| data.records:write | Required | Add, change and delete records |
| schema.bases:read | Required | See your bases, tables and fields |
| data.recordComments:read | Optional | See comments on records |
| data.recordComments:write | Optional | Add comments to records |

Avox's connect page shows the same list. A token without a required scope is refused
([AVX-3727](https://docs.theavoxai.com/error-codes/avx-3727)), as is a token Airtable does not accept
([AVX-3686](https://docs.theavoxai.com/error-codes/avx-3686)). Without an optional scope, only the actions that need it are
switched off, and they say why ([AVX-3690](https://docs.theavoxai.com/error-codes/avx-3690)). To add one later, edit the token
in Airtable and click **Test connection**.

> **Note**
>
> The token is stored encrypted and is never shown again, not even to you.

## What you see in Avox afterwards

Open **Apps**, then **Airtable**. The menu has **Overview**, **Sheets** and **Activity**.

- **Overview** shows the status, your Airtable account, the **Default base**, who connected it and
  the last problem with its code. **Test connection** says whether Airtable accepted the token and
  the default base, and whether comments are off.
- **Sheets** has **Sent by Avox** (the tables Avox read or wrote) and **In Airtable** (every table
  the token can open, with **Load more**). A table's page shows its fields, views and first 20
  records. A record's page shows every field and its comments, with **Open in Airtable**, **Add a
  comment** and **Delete record** (asks first; both need **Manage connected apps**).
- **Activity** has **Usage** (calls per day over 7, 30 or 90 days) and the **Log** of every call.

The status is **Connected**, **Needs reconnecting** or **Having trouble**.

## Using Airtable in Avox

Flows do not call Airtable directly. To save a Flow's answers, make an automation that starts with
**Flow submitted**. Add a **Use a connected app** step and pick what to do under **Airtable**:
**Find Airtable records**, **Get an Airtable record**, **Add an Airtable record**, **Update an
Airtable record**, **Add or update an Airtable record**, **Delete an Airtable record** (you confirm
it in the step first), **Add files to an Airtable record** and **Comment on an Airtable record**.
Steps are free (no credits), and let you pick bases, tables, views and fields from Airtable.

Fill each field with fixed text or values like `{{flow.email}}`. Later steps use the record's
fields by name, like `{{record.first_name}}`, plus its id. A find sets `{{records.count}}` and
the first record's fields; set **If nothing matches** to stop or carry on. **Add or update** needs
1 to 3 **match** fields, like Email, filled in every time ([AVX-3738](https://docs.theavoxai.com/error-codes/avx-3738)).

Automations can use only three details of the person in the chat: `{{contact.name}}`,
`{{contact.first_name}}` and `{{contact.phone_last4}}` (the last 4 digits), plus your own custom
contact fields. The full phone number is not offered, so ask for it in the Flow or read it from a
table row.

Avox writes each value the way its field needs: numbers like `1250`, checkboxes as yes or no, a
select by its option's name, dates like `2026-10-25`, files as https links. A value that does not
fit fails the step ([AVX-3731](https://docs.theavoxai.com/error-codes/avx-3731)). **Filter formulas** are Airtable's own, like
`{Status} = 'Open'` ([AVX-3732](https://docs.theavoxai.com/error-codes/avx-3732)).

**Worked example (made up for illustration).** A booking Flow asks for name, email and party size.
An automation starts with **Flow submitted** and has one step, **Add or update an Airtable record**,
on a table called Bookings: **Email** `{{flow.email}}`, **Name** `{{flow.name}}`, **Party size**
`{{flow.party_size}}`, matching on **Email**. Use your own table and Flow field names. A returning
customer updates their record instead of adding a new one.

The premade automation **Save Flow answers to Airtable** starts you off. It adds a record from a
Flow's answers and thanks the customer, with the Airtable step set to carry on if it fails. Pick your
Flow, base and table. The sheet steps also work with Airtable: the "sheet" is a base and a table.

## Limits

- Airtable allows 5 requests a second per base, and Avox spaces its calls out. Each Switchboard
  can make 120 calls a minute to Airtable ([AVX-3695](https://docs.theavoxai.com/error-codes/avx-3695)).
- Avox adds, updates and deletes up to 10 records per call ([AVX-3733](https://docs.theavoxai.com/error-codes/avx-3733)), and
  adds up to 10 files per call. A step fills up to 50 fields. A find returns 1 to 100 records (10 if
  you do not say).
- Lists come 100 at a time. Airtable's plans limit calls and records
  ([AVX-3737](https://docs.theavoxai.com/error-codes/avx-3737)). Each try gives up after 10 seconds.

## When Airtable fails or says no

1. **Retries.** Reads, updates, add-or-update and deletes are tried again, up to two more times
   after about 0.4 and 1.2 seconds, when Airtable is unreachable or answers 429, 502, 503 or 504
   (Avox honours a wait of up to 5 seconds). Adding a record, adding files and adding a comment are
   not repeated after a failure, because they might have gone through. If Airtable says slow down,
   it did nothing, so Avox waits 1 second and tries again, then 2 seconds, for every action.
2. **The log.** Each call is logged with its tries. For records the log keeps counts and ids, not
   the values.
3. **The status.** If Airtable stops accepting the token (deleted or revoked), the status becomes
   **Needs reconnecting** at once ([AVX-3692](https://docs.theavoxai.com/error-codes/avx-3692)). Five failed calls in a row
   from Airtable's side make it **Having trouble**, and one good call makes it **Connected** again.
   A wrong base, table, field or value, a missing scope or a plan limit does not count against its
   health.
4. **Your automation.** The step stops the run or carries on, as you chose in **If it can't be
   done** (the default is **Stop the run**). While Airtable **Needs reconnecting**, the step does not
   call Airtable and fails with [AVX-3596](https://docs.theavoxai.com/error-codes/avx-3596) in the run log. Other failures show
   [AVX-3605](https://docs.theavoxai.com/error-codes/avx-3605).
5. **The pages.** If a list cannot be read, the page shows what Avox saved, with
   [AVX-3717](https://docs.theavoxai.com/error-codes/avx-3717).

**What happens to the person's data.** If the save fails, that record is not in Airtable, and Avox
does not try it again later on its own. The chat goes on and the Flow answers stay in your Inbox.
Correct the cause and run the automation again.

Codes you may see: [AVX-3728](https://docs.theavoxai.com/error-codes/avx-3728) base not reachable,
[AVX-3729](https://docs.theavoxai.com/error-codes/avx-3729) table not found, [AVX-3730](https://docs.theavoxai.com/error-codes/avx-3730) field not
found, [AVX-3734](https://docs.theavoxai.com/error-codes/avx-3734) record gone, [AVX-3735](https://docs.theavoxai.com/error-codes/avx-3735) file link
not usable, [AVX-3736](https://docs.theavoxai.com/error-codes/avx-3736) no base named and no default,
[AVX-3694](https://docs.theavoxai.com/error-codes/avx-3694) Airtable is not answering, and
[AVX-3711](https://docs.theavoxai.com/error-codes/avx-3711) the Switchboard is paused.

## Disconnecting

Click **Disconnect** on Airtable's Overview. Avox shows what uses it and deletes the token it saved.
Airtable is not told, so also delete the token in Airtable's Builder hub. The log and usage stay for
your retention period, and your records stay in Airtable. Steps that use Airtable fail until you
connect again.

## Common questions

**Avox cannot see my base**

The token only opens the bases listed under **Access**. Add the base in Airtable
([AVX-3728](https://docs.theavoxai.com/error-codes/avx-3728)).

**Can I switch to a token from another Airtable account?**

Not while connected. Reconnecting with a token from a different Airtable account is refused
([AVX-3703](https://docs.theavoxai.com/error-codes/avx-3703)). Disconnect first to switch.

## Related