Skip to main content
Slate’s Signatures API handles e-signature and e-notary ceremonies for legal recovery documents. The system is built around two objects that work together: a signature request represents a single Slate document that needs to be signed, and a signature transaction bundles one to one hundred requests into a session assigned to a signer, and optionally a notary, who completes them in a single ceremony. Your integration creates requests, bundles them into a transaction, retrieves a signing URL, and polls the transaction until it reaches a terminal state.

​
Core Objects

Signature request — A single Slate document queued for signing. The only required field on creation is fileId, the UUID of an existing Slate file. (documentId is a deprecated alias still accepted for backwards compatibility.) Slate populates the rest from the file itself, including a file.templates array where each template flags whether a signature and/or a notary seal is required. Signature transaction — A signing session that groups one or more signature requests for a specific signer and (optionally) notary. The transaction produces the signing URL and manages the ceremony lifecycle from pending through completed or failed.

​
Signing Workflow

1

Create a signature request for each document

For each document that needs to be signed, call POST /v2/requests with the fileId of an existing Slate file.
Save the id returned on the SignatureRequest object. You will pass these IDs into the transaction in the next step. Inspect the returned file.templates[].notaryRequired values to determine whether the transaction will need a notary.
2

Create a signature transaction

Call POST /v2/transactions with your owner, the signerId, the array of signatureRequests IDs to bundle (1 to 100), and, if any template on any request sets notaryRequired: true, a notaryId. You can also pass an IANA timezoneId (for example, America/New_York) to display timestamps in the signer’s local time during the ceremony.
Slate validates file sizes, media types, and notary requirements before accepting the transaction. On failure, the 400 response includes a structured error with a message, a files array, and a reason code such as NOTARY_REQUIRED, EXCEEDS_MAX_FILE_SIZE, or INVALID_MEDIA. See Create Transaction for the full list.
3

Retrieve the signing URL

Call GET /v2/transactions/{id}/signing-url to get a short-lived URL you can redirect the signer to. Generate this URL immediately before you need it, do not cache it.
4

Signer completes the ceremony

The signer opens the signingUrl and completes the ceremony in the configured provider’s interface. If otpRequired: true on the transaction, the ceremony first prompts the signer for a one-time passcode delivered via the channel indicated by otpMethod (email or sms). For notarized transactions, the notary joins through the provider’s remote online notarization flow.
5

Poll the transaction until it reaches a terminal state

Call GET /v2/transactions/{id} to check status. The transaction moves through several lifecycle timestamps: signingStartedOn when the earliest signing starts, signingCompletedOn when the latest signing completes, notaryReadyOn when the notary joins, notaryStartedOn and notaryCompletedOn around notarization, and finally completedOn (or failedOn on failure).
Once complete, fetch each signature request via GET /v2/requests/{id} to get its completedFileUrl, a URL where the executed document can be downloaded.

​
Transaction Statuses

​
Notary Support

Notary requirements come from the templates on each signature request. When any file.templates[].notaryRequired is true on any request in the bundle, the transaction must include a notaryId. Omitting it makes POST /v2/transactions return a 400 whose body carries reason: "NOTARY_REQUIRED" alongside a message and a files array. Inspect a signature request with GET /v2/requests/{id} before creating the transaction to determine whether a notary is needed. For notarized transactions, notaryReadyOn is set after the signer finishes their portion, and completedOn is set after the notary finishes their review.

​
One-Time Passwords (OTP)

Some transactions require additional identity verification before the signer can access the ceremony. Check the transaction’s otpRequired and otpMethod fields:
  • If otpRequired: true, the signer must enter a one-time passcode before the ceremony begins.
  • otpMethod specifies how the code is delivered: email or sms.
Communicate to the signer which channel to check so they know where to expect the code.

​
Rejecting a Signature Request

To take a document out of a signing workflow without deleting it, call PATCH /v2/requests/{id} with { "status": "rejected" } (rejected is the only allowed status value). The response returns the request id, status, and a rejected_on timestamp. Rejection is irreversible; create a new signature request if you need to restart. To permanently remove a request that has not been completed, use DELETE /v2/requests/{id} instead.

​
Signature Providers

Slate abstracts the underlying e-signature provider behind a consistent API surface. The active provider is configured at the owner level and is reported on the transaction via signatureProvider. Your code for creating transactions, checking status, and retrieving completed documents remains the same regardless of provider.
If you need to know which provider is configured for a specific owner, for example for compliance documentation, contact your Slate account manager.