Skip to content

Databases and app builders

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.

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.

Before you start

  • A SignatureAPI test API key (it starts with key_test_).
  • The document you send, at a URL on a supported host, or uploaded to SignatureAPI first. The script uses a sample PDF.
  • A table with name and email fields, and a field for the envelope id. Airtable 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).

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().

3

Keep the key in a secret

Airtable’s Run script article 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(). 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().

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).

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.

SettingValue
Method POST
URL https://api.signatureapi.com/v1/envelopes
Header X-API-Key: YOUR_API_KEY

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

Header Content-Type: application/json
Body (raw JSON)The JSON below.
Body (raw 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 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 in test mode with the Airtable URL. Subscribe to envelope.completed, 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.

SettingValue
Method GET
URL https://api.signatureapi.com/v1/envelopes/eb4cf433-a8af-4161-b37b-7ef57d423e56
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.