Skip to content

Databases and app builders

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.

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

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

Retool HTTP request step

Settings for the "Service agreement" request.

SettingValue
Method POST
URL /v1/envelopes

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

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": "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.

SettingValue
Method GET
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 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.

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.

SettingValue
Method GET
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, send your API key with the download.