> ## Documentation Index
> Fetch the complete documentation index at: https://docs.slate.inc/llms.txt
> Use this file to discover all available pages before exploring further.
# E-Signatures and E-Notary Transactions in Slate API
> Create signature requests from Slate documents, bundle them into a signing transaction, retrieve a signing URL, and track the ceremony to completion.
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
For each document that needs to be signed, call `POST /v2/requests` with the `fileId` of an existing Slate file.
```bash theme={null}
curl --request POST \
--url "https://api.slate.inc/signatures/v2/requests" \
--header "Authorization: Bearer " \
--header "Content-Type: application/json" \
--data '{
"fileId": "doc-22222222-0001-0001-0001-000000000001"
}'
```
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.
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.
```bash theme={null}
curl --request POST \
--url "https://api.slate.inc/signatures/v2/transactions" \
--header "Authorization: Bearer " \
--header "Content-Type: application/json" \
--data '{
"owner": "",
"signerId": "u-33333333-0001-0001-0001-000000000001",
"notaryId": "u-66666666-0001-0001-0001-000000000001",
"timezoneId": "America/New_York",
"signatureRequests": [
"sr-11111111-0001-0001-0001-000000000001",
"sr-11111111-0002-0002-0002-000000000002"
]
}'
```
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](/api-reference/signatures/create-transaction) for the full list.
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.
```bash theme={null}
curl --request GET \
--url "https://api.slate.inc/signatures/v2/transactions/txn-aaaaaaaa-0001-0001-0001-000000000001/signing-url" \
--header "Authorization: Bearer "
```
```json theme={null}
{
"signingUrl": "https://signing.slate.inc/ceremony/txn-aaaaaaaa-0001-0001-0001-000000000001?token=..."
}
```
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.
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).
```json theme={null}
{
"id": "txn-aaaaaaaa-0001-0001-0001-000000000001",
"status": "completed",
"createdOn": "2024-11-20T09:15:00Z",
"signingStartedOn": "2024-11-21T13:45:00Z",
"signingCompletedOn": "2024-11-21T13:57:00Z",
"notaryReadyOn": "2024-11-21T13:58:00Z",
"completedOn": "2024-11-21T14:30:00Z",
"failedOn": null
}
```
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
| Status | Meaning |
| ----------- | -------------------------------------------------------------------------------------------------------- |
| `pending` | The transaction has been created and the signing URL is active. Awaiting signer (and notary) action. |
| `completed` | The ceremony finished successfully. Signed documents are available on each request's `completedFileUrl`. |
| `failed` | The ceremony encountered an unrecoverable error. Create a new transaction to retry. |
## 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.
```json theme={null}
{
"otpRequired": true,
"otpMethod": "sms"
}
```
## 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.