API quick start

Create an API key, make your first request, and learn how errors, limits, retries and pagination work in the eSignStack API.

Create an API key

1. Open Developers → API keys and click Create key.
2. Enter a Key name and, if you want, an Expiry.
3. Choose the Key mode: Test for sandbox data or Live for real envelopes.
4. Choose abilities. Read only, Send envelopes and Full access fill in common sets; you can change them one by one.
5. Copy the secret from the dialog. It's shown once and can't be retrieved later.

Workspace owners, admins and developers can manage keys. Developers can only issue keys with the webhooks:read, webhooks:write and keys:write abilities. To revoke a key, open its ⋯ menu and click Revoke, or call DELETE /api/v1/api_keys/{key}.

Keep secrets on your server. Never put a key in browser code, a mobile app, logs or source control.

Key types

A key only sees data in its own mode: a test key can't read live envelopes, and a live key can't read test ones. Test keys create and send watermarked test envelopes, from a file or a template, and nothing counts toward your limits. SMS verification is refused in test mode (422), and changing brand kits, folders, filing rules or identity providers needs a live key (403 live_key_required). See Sandbox for more. A platform key acts inside a workspace when you send Workspace-Id: ws_…; see the platform integration guide.

Abilities

Every key lists its abilities explicitly. There are no wildcards.

Platform keys can also hold platform:read (read the platform's settings and members), workspaces:read, workspaces:write, login_links:write and identity_providers:write. A key created through the API (POST /api/v1/api_keys) has the same mode as the key that created it, so a test key can only issue test keys. It also can't have abilities its creator doesn't have, and can't outlive it.

Make your first request

The base URL is https://esignstack.app/api/v1. Send the key as a bearer token. This request returns the key's own details and needs no ability:

curl https://esignstack.app/api/v1/api_keys/current \
  -H "Authorization: Bearer $ESIGNSTACK_KEY"

Objects use prefixed IDs such as env_…, rcp_…, tpl_… and file_…. JSON keys are snake_case. Every object has object, id, created (a UTC timestamp such as 2026-11-02T18:15:00+00:00) and livemode.

Create an envelope from a template

Get the template's role labels with GET /api/v1/templates/{template}, then map each person to a role:

curl -X POST https://esignstack.app/api/v1/templates/$TEMPLATE_ID/envelopes \
  -H "Authorization: Bearer $ESIGNSTACK_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-456-create" \
  -d '{
    "name": "Acme service agreement",
    "recipients": [
      {"role_label": "Client", "name": "Jane Doe", "email": "jane@example.com"}
    ],
    "external_id": "order-456",
    "send": false
  }'

Roles that the template always sends to the same person (recipient_email on the role) are filled in for you, so you can leave them out. Include one to send that role to someone else on this envelope.

send defaults to true. With send: false the envelope stays a draft so you can check it, then send it with POST /api/v1/envelopes/{envelope}/send. values fills template fields by label. To start from your own PDF instead, see the Envelopes API.

Idempotency keys

Send an Idempotency-Key header (up to 255 characters) on POST requests, and reuse it when you retry the same request after a timeout.

• A repeat of a completed request returns the stored response with Idempotent-Replayed: true.
• The same key with a different request returns 409 idempotency_key_reused.
• A request still running returns 409 idempotency_key_in_progress with Retry-After.
• Requests that fail don't use up the key. Keys are kept for 24 hours.
• The header is ignored on POST /verify, POST /login_identities/{id}/deprovision and POST /identity_providers/{idp}/subjects/{sub}/deprovision.

Errors

Errors return JSON with an error object:

{
  "error": {
    "type": "invalid_request_error",
    "code": "validation_failed",
    "message": "The name field is required.",
    "param": "name",
    "doc_url": "https://esignstack.app/docs/api#validation_failed",
    "request_id": "req_01J…"
  }
}

Every response has a Request-Id header. Include it when you contact support.

API envelope limits

API and MCP envelopes have their own monthly allowance. An envelope counts when it's sent through the API or MCP in live mode, or when the API issues a signing session for an envelope that was sent another way. Test envelopes never count.

Yearly plans get 12 months of allowance up front (for example, 600 on Starter). On Platform, envelopes past the allowance are billed as you go. You can set a monthly spending cap on extra envelopes on the Billing page.

When a send is refused, the API returns 422 with code validation_failed, param set to document, and a quota object that says which limit was hit and when it resets:

"quota": { "code": "api_envelope_limit_reached", "resets_at": "2026-11-01T00:00:00Z" }

GET /api/v1/usage (ability usage:read) returns current usage, including api_envelopes with used, limit, remaining and resets_at. A platform key without Workspace-Id also gets platform, the platform's own allowance, extras and spending cap.

Rate limits

Each key can make 100 requests a second, and each workspace 6,000 requests a minute across all its keys. Responses carry RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and RateLimit-Policy. Over the limit you get 429 with Retry-After; wait that long before retrying.

Versions

The current version is 2026-10-14. Each key is pinned to the version current when it was created. Send Api-Version to choose a version per request; responses echo the version used. New fields can appear in responses at any time, so ignore fields you don't recognize.

Pagination

List endpoints return object: "list", data, has_more and url, newest first. Use limit (1 to 100, default 20) and pass the last ID you received as starting_after to get the next page, or the first ID as ending_before to go back. Some endpoints take expand[], for example expand[]=recipients on envelopes.

The full list of endpoints, fields and filters is in the API reference.