Skip to content

Explore

API Overview

How the SignatureAPI REST API works: base URL, request anatomy, HTTP methods and status codes, the endpoint list, and the versioning policy.

SignatureAPI API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes and methods.

Your backend calls the API with an API key. Recipients sign in a ceremony, and webhooks report each change back to your backend.

How SignatureAPI fits in your stack
How SignatureAPI fits in your stack6 parts: Your backend, Webhook endpoint, API, Envelope, Event, Ceremony. Connections: Your backend to API (HTTPS requests); API to Envelope (creates); Envelope to Ceremony (signing link); Envelope to Event (status changes); Event to Webhook endpoint (webhooks).Your systemsSignatureAPIYour recipientsYour backendWebhook endpointAPIEnvelopeEventCeremonyHTTPS requestscreatessigning linkstatus changeswebhooks
Your systemsSignatureAPIYour recipientsSignatureAPI (continued)Your systems (continued)Your backendAPIEnvelopeCeremonyEventWebhook endpointHTTPS requestscreatessigning linkstatus changeswebhooks

Asynchronous: SignatureAPI calls your endpoint when something changes.

Diagram as text

Parts

  • Your backend: Holds the API key and creates envelopes.
  • Webhook endpoint: Receives events and verifies their signatures.
  • API: Checks the API key in X-API-Key and validates each request.
  • Envelope: Holds the documents and recipients and moves through its lifecycle.
  • Event: Records each status change of an envelope, recipient or deliverable.
  • Ceremony: Opened from the signing email or embedded in your app.

Connections

  • Your backend to API: HTTPS requests
  • API to Envelope: creates
  • Envelope to Ceremony: signing link
  • Envelope to Event: status changes
  • Event to Webhook endpoint: webhooks

Base URL

The base URL is https://api.signatureapi.com for both test and live modes.

For example, to create an envelope, you do a POST request to https://api.signatureapi.com/v1/envelopes.

Anatomy of a request

Every request sends the API key in the X-API-Key header. Requests with a body send JSON with Content-Type: application/json. The numbered notes explain each part of a request and its response.

Request
POST /v1/envelopes HTTP/1.1Host: api.signatureapi.comX-API-Key: YOUR_API_KEYContent-Type: application/json {  "title": "Service Agreement",  "documents": [    {      "url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/acme-service-agreement.pdf",      "places": [        {          "key": "client_signs_here",          "type": "signature",          "recipient_key": "client"        },        {          "key": "provider_signs_here",          "type": "signature",          "recipient_key": "provider"        }      ]    }  ],  "recipients": [    {      "type": "signer",      "key": "client",      "name": "Jane Doe",      "email": "jane.doe@example.com"    },    {      "type": "signer",      "key": "provider",      "name": "John Smith",      "email": "john.smith@example.com"    }  ]}
  1. Method and path Creating an envelope is a POST to /v1/envelopes.
  2. Authentication Send your API key in the X-API-Key header. A test key creates test-mode envelopes.
  3. Body Three fields are required: title, documents (at least one, each with a public file url) and recipients (at least one). Each place ties a placeholder in the PDF to a recipient key.
Response
HTTP/1.1 201 CreatedContent-Type: application/json {  "id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",  "status": "processing",  "mode": "test"}
  1. Status 201 Created means the envelope was created and is being processed.
  2. Result The envelope id is a plain UUID. It starts in processing and moves to in_progress.

HTTP Semantics

We use HTTP methods GET, POST, DELETE as defined in RFC 9110, and PATCH as defined in RFC 5789.

We use the following HTTP Status codes for successful responses:

Status CodeDescription
200 OKRequest succeeded for a GET, POST, or PATCH call.
201 CreatedRequest succeeded for a POST request that created a new resource. The response includes a Location header pointing to the newly created resource.
204 No ContentRequest succeeded for a DELETE request. The response has no body.

Failed requests return a 4XX or 5XX status with a problem details body. See Errors.

Endpoints

Versioning

The current version of the API is v1. We will increment the version number if we make a change that breaks backward compatibility.

These are not breaking changes:

  • Any additive change, such as adding endpoints, optional arguments, or enum values.
  • Making a required request parameter optional.
  • Making a validation less restrictive.
  • Changes to error responses.
  • Changes to the order of fields returned in a response.
  • Changes to the length or format of opaque strings, such as object IDs, error messages, and other human-readable strings.
  • Adding new event types.