---
title: "Send Agreements From a Retool App"
description: "Build a Retool app that creates SignatureAPI envelopes from a form and lists them in a table, using a REST API resource with the API key in its headers."
canonical: "https://signatureapi.com/docs/integrations/retool"
source: "https://signatureapi.com/docs/integrations/retool.md"
last_verified_api_version: "1.18.0"
---

# Send Agreements From a Retool App

Build a Retool app that creates SignatureAPI envelopes from a form and lists them in a table, using a REST API resource with the API key in its headers.

_Last verified against API version 1.18.0._

Retool calls the SignatureAPI REST API through its own **REST API** resource. The resource holds the base URL and the `X-API-Key` header, one query creates the envelope from a form, and another lists envelopes in a table. No SignatureAPI app is needed.

## 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 examples use a sample PDF.

## Send the envelope

1. **Create the resource**

   In Retool, open **Resources**, click **Create new** > **Resource**, and select **REST API**. Enter `https://api.signatureapi.com` as the **Base URL**. Under headers, add `X-API-Key` with your key as the value. Retool [includes resource headers](https://docs.retool.com/data-sources/guides/connect/rest) on every request that uses the resource, and lets you redact a header's value from logs and the Debug Tools console. Click **Test connection** and then **Create resource**.

2. **Add a form**

   Add a form to the app with inputs for the signer's name and email, for example `nameInput` and `emailInput`.

3. **Create the query**

   In the query editor, select the resource, set **Action type** to `POST` and the URL path to `/v1/envelopes`. Choose **Raw** in the **Body** section and add a `Content-Type` header with the value `application/json`. Paste the body below and wrap the form values in `{{ }}`, such as `{{ nameInput.value }}`.

4. **Run it from the form**

   A `POST` query runs only when triggered, so add an event handler on the form's submit that runs the query ([Retool queries guide](https://docs.retool.com/queries/guides/api/rest)).

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

1. **Method**: POST
2. **URL**: `/v1/envelopes`

   Relative to `https://api.signatureapi.com`. The base URL and the API key come from the setup in the steps above.
3. **Header**: `Content-Type: application/json`
4. **Body (raw JSON)**:

   ```json
   {
     "title": "Service Agreement - Jane Doe",
     "message": "Please review and sign the service agreement.",
     "metadata": {
       "source": "retool",
       "customer_id": "cus_1042"
     },
     "topics": [
       "no_code",
       "retool"
     ],
     "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.customer_id` comes back in every webhook event for this envelope, and the `retool` topic lets you list only these envelopes. In a Raw body, put quotes around each `{{ }}` string value, as Retool describes.

## List the envelopes

Create a second query on the same resource with `GET` and the URL path `/v1/envelopes`. By default Retool runs `GET` queries automatically when their inputs change. Add the `topic` and `limit` parameters:

Retool HTTP request step settings for the "Retool envelopes" request:

1. **Method**: GET
2. **URL**: `/v1/envelopes?topic=retool&limit=20`

   Relative to `https://api.signatureapi.com`. The base URL and the API key come from the setup in the steps above.

Add a Table component and set its **Data source** to the query's data, as in `{{ listEnvelopes.data.data }}`. [Retool](https://docs.retool.com/apps/guides/data/table) needs an array of objects, and the table builds its columns from their keys. SignatureAPI returns the envelopes in a `data` array, newest first, so the second `data` is that array. A list returns up to 20 envelopes per call. See [Pagination](https://signatureapi.com/docs/api/pagination).

## Show one envelope

For a detail view, add a query that reads one envelope when a table row is selected, with the envelope id in the URL path:

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

1. **Method**: GET
2. **URL**: `/v1/envelopes/eb4cf433-a8af-4161-b37b-7ef57d423e56`

   Relative to `https://api.signatureapi.com`. The base URL and the API key come from the setup in the steps above.

The response gives the envelope `status`, each recipient's status, and the deliverable. The deliverable has its own `status`: `deliverable.url` downloads the signed PDF once `deliverable.status` is `generated`, which can be a little after the envelope turns `completed`. That link expires after an hour, so read the envelope again for a fresh one. If your account uses [authenticated deliverable URLs](https://signatureapi.com/docs/api/resources/deliverables/object#url), send your API key with the download.

## Related

- [Create an envelope](https://signatureapi.com/docs/api/resources/envelopes/create): every field of the request body.
- [List envelopes](https://signatureapi.com/docs/api/resources/envelopes/list): filters and pagination.
- [Rate limits](https://signatureapi.com/docs/api/rate-limiting): 10 requests per second per key.

### Example: Service agreement

Sent from a Retool query.

```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": "retool",
    "customer_id": "cus_1042"
  },
  "topics": [
    "no_code",
    "retool"
  ],
  "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": "retool",
    "customer_id": "cus_1042"
  },
  "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",
    "retool"
  ],
  "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.
