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.
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.
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" } ]} - Method and path Creating an envelope is a
POSTto/v1/envelopes. - Authentication Send your API key in the
X-API-Keyheader. A test key creates test-mode envelopes. - Body Three fields are required:
title,documents(at least one, each with a public fileurl) andrecipients(at least one). Each place ties a placeholder in the PDF to a recipientkey.
HTTP/1.1 201 CreatedContent-Type: application/json { "id": "eb4cf433-a8af-4161-b37b-7ef57d423e56", "status": "processing", "mode": "test"} - Status
201 Createdmeans the envelope was created and is being processed. - Result The envelope
idis a plain UUID. It starts inprocessingand moves toin_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 Code | Description |
|---|---|
200 OK | Request succeeded for a GET, POST, or PATCH call. |
201 Created | Request succeeded for a POST request that created a new resource. The response includes a Location header pointing to the newly created resource. |
204 No Content | Request 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.