---
title: "Send Agreements From Airtable Records"
description: "Create a SignatureAPI envelope from an Airtable record with an automation Run script action, and receive the result with a When webhook received trigger."
canonical: "https://signatureapi.com/docs/integrations/airtable"
source: "https://signatureapi.com/docs/integrations/airtable.md"
last_verified_api_version: "1.18.0"
---

# Send Agreements From Airtable Records

Create a SignatureAPI envelope from an Airtable record with an automation Run script action, and receive the result with a When webhook received trigger.

_Last verified against API version 1.18.0._

An Airtable automation can send an agreement when a record is ready. Airtable's own **Run script** action runs JavaScript with `fetch`, so the script calls the SignatureAPI REST API directly. No SignatureAPI app is needed.

Full code on GitHub: [`no-code/airtable`](https://github.com/signatureapi/examples/tree/main/no-code/airtable).

## Before you start

- A SignatureAPI [test API key](https://signatureapi.com/docs/api/test-mode) (it starts with `key_test_`).
- The document you send, at a URL on a [supported host](https://signatureapi.com/docs/api/resources/documents/url#external-store), or [uploaded to SignatureAPI](https://signatureapi.com/docs/api/resources/uploads/create) first. The script uses a sample PDF.
- A table with name and email fields, and a field for the envelope id. [Airtable](https://support.airtable.com/docs/run-a-script-action) offers the Run script action on all plan types, with varying limits, but not on a Team plan trial.

## Send the envelope

1. **Create the automation**

   Create an automation with a trigger such as **When a record matches conditions**. Add a condition that the envelope id field is empty, so each record sends once ([Airtable automations guide](https://support.airtable.com/docs/getting-started-with-airtable-automations)).

2. **Add a Run script action**

   In the action, add the input variables `name`, `email` and `recordId`, and map each to a field of the record. The script reads them with [`input.config()`](https://airtable.com/developers/scripting/api/input).

3. **Keep the key in a secret**

   Airtable's [Run script article](https://support.airtable.com/docs/run-a-script-action) says to store API keys with the **Secrets** feature in the script editor, not in the code. Add a secret named `apiKey` with your key. The script reads it with [`input.secret()`](https://airtable.com/developers/scripting/api/secrets). Once a script uses a secret, only people with access to it can edit the script.

4. **Paste the script**

   The script creates the envelope with `fetch` and returns its id and status with [`output.set()`](https://airtable.com/developers/scripting/api/output).

5. **Save the id**

   Add an **Update record** action after the script. Map its record id to the triggering record, and its envelope id and status fields to the script outputs `envelope_id` and `status` ([Airtable Update record](https://support.airtable.com/docs/update-record-action)).

```javascript
const config = input.config();
const apiKey = input.secret('apiKey');

const response = await fetch('https://api.signatureapi.com/v1/envelopes', {
  method: 'POST',
  headers: { 'X-API-Key': apiKey, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    title: `Service Agreement - ${config.name}`,
    message: 'Please review and sign the service agreement.',
    metadata: { source: 'airtable', record_id: config.recordId },
    topics: ['no_code', 'airtable'],
    documents: [
      {
        key: 'service_agreement',
        url: 'https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf',
        format: 'pdf',
        fixed_positions: [{ place_key: 'signer_signature', page: 1, top: 172, left: 210 }],
        places: [{ key: 'signer_signature', type: 'signature', recipient_key: 'signer' }],
      },
    ],
    recipients: [{ type: 'signer', key: 'signer', name: config.name, email: config.email }],
  }),
});

const envelope = await response.json();
if (!response.ok) throw new Error(`Create envelope failed with ${response.status}`);

output.set('envelope_id', envelope.id);
output.set('status', envelope.status);
```

The script sends this request:

Airtable HTTP request step settings for the "Service agreement" request:

1. **Method**: POST
2. **URL**: `https://api.signatureapi.com/v1/envelopes`
3. **Header**: `X-API-Key: YOUR_API_KEY`

   Store the key in Airtable's secret or credential storage when it has one.
4. **Header**: `Content-Type: application/json`
5. **Body (raw JSON)**:

   ```json
   {
     "title": "Service Agreement - Jane Doe",
     "message": "Please review and sign the service agreement.",
     "metadata": {
       "source": "airtable",
       "record_id": "rec8Kx2LmQ4ZpT9Wd"
     },
     "topics": [
       "no_code",
       "airtable"
     ],
     "documents": [
       {
         "key": "service_agreement",
         "url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf",
         "format": "pdf",
         "fixed_positions": [
           {
             "place_key": "signer_signature",
             "page": 1,
             "top": 172,
             "left": 210
           }
         ],
         "places": [
           {
             "key": "signer_signature",
             "type": "signature",
             "recipient_key": "signer"
           }
         ]
       }
     ],
     "recipients": [
       {
         "type": "signer",
         "key": "signer",
         "name": "Jane Doe",
         "email": "jane.doe@example.com"
       }
     ]
   }
   ```

`data.envelope_metadata.record_id` comes back in every webhook event for this envelope, and the `airtable` topic lets an endpoint receive only these envelopes. Airtable limits a script to 50 `fetch` requests and a 30-second `fetch`.

## Get the result back

Airtable automations can start from an incoming webhook. Add the **When webhook received** trigger, and Airtable generates a URL that accepts a `POST` with a JSON object. [Airtable](https://support.airtable.com/docs/when-webhook-received-trigger) offers it on all plan types with varying limits, allows five requests per second, and doesn't verify request signatures.

1. **Register the URL in SignatureAPI**

   In the Dashboard, add a [webhook endpoint](https://signatureapi.com/docs/api/guides/how-to/set-up-webhooks) in test mode with the Airtable URL. Subscribe to [`envelope.completed`](https://signatureapi.com/docs/api/resources/events/envelope-events), and add the `airtable` topic. Airtable asks for an example request before you continue, so complete a test envelope to send one.

2. **Read the envelope before you act**

   Airtable can't check who called the URL, so read the envelope with your key before you update anything. Add a **Run script** action that maps `data.envelope_id` from the event to an input variable, with the same `apiKey` secret, and sends this request:

   Airtable HTTP request step settings for the "Completed envelope" request:

   1. **Method**: GET
   2. **URL**: `https://api.signatureapi.com/v1/envelopes/eb4cf433-a8af-4161-b37b-7ef57d423e56`
   3. **Header**: `X-API-Key: YOUR_API_KEY`

      Store the key in Airtable's secret or credential storage when it has one.

   Return `status` and `metadata.record_id` with `output.set()`. The `metadata.record_id` value names the record to update.

3. **Update the record**

   Add an **Update record** action. Set its record id to the script's `record_id` output, and its status field to the `status` output.

SignatureAPI expects a `2XX` answer and retries a failed delivery for up to 48 hours. The same event can arrive twice, so skip a record that already shows as signed. See [Webhooks](https://signatureapi.com/docs/api/webhooks).

## Related

- [Create an envelope](https://signatureapi.com/docs/api/resources/envelopes/create): every field of the request body.
- [Organize with topics and metadata](https://signatureapi.com/docs/api/guides/how-to/organize-topics-metadata).
- [Make](https://signatureapi.com/docs/integrations/make), [Zapier](https://signatureapi.com/docs/integrations/zapier/http-recipe) and [n8n](https://signatureapi.com/docs/integrations/n8n) use the same request.

### Example: Service agreement

The body the Airtable script sends.

```http
POST /v1/envelopes HTTP/1.1
Host: api.signatureapi.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{
  "title": "Service Agreement - Jane Doe",
  "message": "Please review and sign the service agreement.",
  "metadata": {
    "source": "airtable",
    "record_id": "rec8Kx2LmQ4ZpT9Wd"
  },
  "topics": [
    "no_code",
    "airtable"
  ],
  "documents": [
    {
      "key": "service_agreement",
      "url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf",
      "format": "pdf",
      "fixed_positions": [
        {
          "place_key": "signer_signature",
          "page": 1,
          "top": 172,
          "left": 210
        }
      ],
      "places": [
        {
          "key": "signer_signature",
          "type": "signature",
          "recipient_key": "signer"
        }
      ]
    }
  ],
  "recipients": [
    {
      "type": "signer",
      "key": "signer",
      "name": "Jane Doe",
      "email": "jane.doe@example.com"
    }
  ]
}
```

Response 201 Created:

```json
{
  "id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
  "title": "Service Agreement - Jane Doe",
  "label": null,
  "message": "Please review and sign the service agreement.",
  "status": "processing",
  "attestation": "none",
  "language": "en",
  "mode": "test",
  "routing": "sequential",
  "timezone": "UTC",
  "timestamp_format": "MM/DD/YYYY HH:mm:ss",
  "snapshot_url": null,
  "branding": {
    "logo": null,
    "accent_color": "#2463EB",
    "email": {
      "footer": null,
      "logo_position": "left",
      "from": "noreply@signatureapi.com"
    }
  },
  "deliverable": {
    "id": "del_6FF89lKNyTNamOJCJd1tLL",
    "envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
    "name": null,
    "status": "pending",
    "type": "standard",
    "url": null,
    "password": null,
    "created_at": "2026-11-02T14:03:11.000Z",
    "generated_at": null,
    "timezone": "UTC",
    "language": "en",
    "timestamp_format": "MM/DD/YYYY HH:mm:ss",
    "included_documents": [
      "service_agreement"
    ]
  },
  "metadata": {
    "source": "airtable",
    "record_id": "rec8Kx2LmQ4ZpT9Wd"
  },
  "sender": {
    "name": "Acme Corp Legal",
    "email": "legal@acme.example",
    "organization": "Acme Corp"
  },
  "captures": {},
  "documents": [
    {
      "id": "doc_HVl3Nj7XzTzX7jN3lVH5vn",
      "envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
      "key": "service_agreement",
      "title": null,
      "page_count": 1,
      "url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf",
      "format": "pdf",
      "fixed_positions": [
        {
          "page": 1,
          "top": 172,
          "left": 210,
          "place_key": "signer_signature"
        }
      ],
      "places": [
        {
          "key": "signer_signature",
          "type": "signature",
          "recipient_key": "signer",
          "height": 60
        }
      ]
    }
  ],
  "recipients": [
    {
      "id": "re_49r1R2jpPDz8hSpP75ZkPp",
      "envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
      "type": "signer",
      "key": "signer",
      "email": "jane.doe@example.com",
      "name": "Jane Doe",
      "ceremony": {
        "authentication": [
          {
            "type": "email_link",
            "subject_override": null,
            "message_override": null
          }
        ],
        "embeddable_in": [],
        "redirect_url": null,
        "redirect_delay": 3,
        "url": null,
        "url_variant": "standard"
      },
      "ceremony_creation": "automatic",
      "delivery_type": "email",
      "signature_options": [
        "typed",
        "drawn"
      ],
      "status": "pending",
      "status_updated_at": "2026-11-02T14:03:11.000Z",
      "completed_at": null
    }
  ],
  "topics": [
    "no_code",
    "airtable"
  ],
  "created_at": "2026-11-02T14:03:11.000Z",
  "completed_at": null
}
```

Response 422 Unprocessable Content:

```json
{
  "type": "https://signatureapi.com/docs/v1/errors/validation-error",
  "title": "Validation Error",
  "status": 422,
  "errors": [
    "recipients[0].email must be a valid email address."
  ]
}
```

Errors that any request can return (authentication, rate limits, server errors) are on the [Errors](https://signatureapi.com/docs/api/errors) and [Authentication](https://signatureapi.com/docs/api/authentication) pages.
