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
- 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 examples use a sample PDF.
Send the envelope
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.
Add a form
Add a form to the app with inputs for the signer’s name and email, for example nameInput and emailInput.
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 }}.
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.
| Setting | Value |
|---|---|
| Method | POST |
| URL | /v1/envelopes Relative to |
| Header | Content- |
| Body (raw JSON) | The JSON below. |
{
"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.
| Setting | Value |
|---|---|
| Method | GET |
| URL | / Relative to |
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.
| Setting | Value |
|---|---|
| Method | GET |
| URL | / Relative to |
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.
Related
- Create an envelope: every field of the request body.
- List envelopes: filters and pagination.
- Rate limits: 10 requests per second per key.
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"
}
]
}npx signatureapi envelopes create --body - <<'EOF'
{
"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"
}
]
}
EOF{
"name": "create_envelope",
"arguments": {
"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"
}
]
}
}{
"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
}{
"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 every call can return are in Errors and Authentication.