# SignatureAPI Base URL: https://signatureapi.com This file combines the published documentation pages into a single text document for AI tools. ## SignatureAPI Docs URL: https://signatureapi.com/docs/api/welcome Description: Integrate electronic signatures into your apps and workflows with SignatureAPI's REST API, no-code connectors, and embedded signing solutions Integrate electronic signatures into your apps and workflows with SignatureAPI. ## Get started ### API Quickstart Link: /docs/api/quickstart Create your first envelope and send it for signature using the REST API. ### Power Automate Quickstart Link: /docs/integrations/power-automate/guides/quickstart Build your first no-code signing workflow in Power Automate. ## What you can do ### Send documents for signature Link: /docs/api/resources/envelopes/create Send to multiple signers in parallel or sequential order. Track every envelope from creation to completion. ### Generate documents from templates Link: /docs/api/resources/documents/templates Fill templates with dynamic data to produce ready-to-sign documents. ### Collect information from signers Link: /docs/api/resources/places/text-input Add input fields, checkboxes, and dropdowns to capture data during signing. ### Embed signing in your app Link: /docs/embedded/introduction Embed the signing experience directly in your web or React Native app. ### Automate with Power Automate Link: /docs/integrations/power-automate/getting-started Build no-code signing workflows connected to 1,000+ apps. ### Get notified via webhooks Link: /docs/api/webhooks Receive real-time updates when envelopes are signed, completed, or canceled. See all capabilities (/docs/api/can_i) ## How it works ### Create an envelope An envelope (/docs/api/resources/envelopes/object) holds your documents (/docs/api/resources/documents/object) and recipients (/docs/api/resources/recipients/object). Add documents directly as PDFs or generate them from templates (/docs/api/resources/documents/templates). ```json // POST https://api.signatureapi.com/v1/envelopes // X-API-Key: key_test_... // Content-Type: application/json { "title": "Dummy Consent", "documents": [ { "format": "pdf", "url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/privacy-placeholder.pdf", "places": [ { "key": "signer_signs_here", "type": "signature", "recipient_key": "visitor" } ] } ], "recipients": [ { "type": "signer", "key": "visitor", "name": "John Doe", "email": "john@example.com" } ] } ``` ### Recipients receive a signing link Each recipient gets a link to review and sign. You can control the signing order (/docs/api/resources/envelopes/routing) and authenticate recipients (/docs/api/resources/ceremonies/authentication/overview) before they access the documents. Image: Signing request email (/docs/api/resources/ceremonies/authentication/email-example.png) ### Recipients sign during a ceremony A ceremony (/docs/api/resources/ceremonies/object) is the guided signing session where recipients review documents and complete their actions. Image: Signing ceremony (/docs/images/quickstart-ceremony.webp) ### Retrieve the signed deliverable After all recipients complete their actions, SignatureAPI generates a deliverable (/docs/api/resources/deliverables/object) containing the signed documents and an audit log. Image: Audit log (/docs/images/audit-log-example.webp) ## Explore ### Concepts Link: /docs/api/concepts Learn the core building blocks: envelopes, documents, recipients, ceremonies, and deliverables. ### API Overview Link: /docs/api/overview Endpoints, authentication, test mode, pagination, and error handling. ### API Playground Link: /docs/api/playground Try the API directly in your browser. ### Postman Collection Link: /docs/api/postman Import our Postman collection and start exploring. ### Embedded Signing Link: /docs/embedded/introduction Integrate the signing experience into your web or mobile app. ### Can I ___? Link: /docs/api/can_i Quick answers to common questions about SignatureAPI capabilities. ## Can I _______ ? URL: https://signatureapi.com/docs/api/can_i Description: Quick answers to common questions about SignatureAPI capabilities including multiple signers, templates, and signature positioning - Can I have multiple signers in my envelope? Yes! (/docs/api/resources/envelopes/create#param-recipients) - Can I have the signers sign in a specific order? Yes! (/docs/api/guides/how-to/sequential-signing) - Can I have multiple documents in my envelope? Yes! (/docs/api/resources/envelopes/create#param-documents) - Can I generate a document from a template and data? Yes! (/docs/api/resources/documents/templates) - Can I place a signature using coordinates (for fixed-layout forms, for example)? Yes! (/docs/api/guides/how-to/use-fixed-positions) - Can I place a signature using a placeholder within the document? Yes! (/docs/api/guides/how-to/use-placeholders) - Can I ask for initials? Yes! (/docs/api/resources/places/initials) - Can I ask my recipients for information (with input fields)? Yes! (/docs/api/resources/places/text-input) - Can I get that recipient input through the API? Yes! (/docs/api/resources/envelopes/captures) - Can I change the language of the signing interface? Yes! (/docs/api/resources/envelopes/language) - Can I use a different time zone (for example America/New_York) for timestamps? Yes! (/docs/api/resources/envelopes/timezone) - Can I use a different date format (for example Month/Day/Year) in timestamps? Yes! (/docs/api/resources/envelopes/timestamp-format) - Can I have the signing URL so I can send it myself to the recipients? Yes! (/docs/api/resources/ceremonies/ceremony-url) - Can I redirect the recipient to a URL after signing? Yes! (/docs/api/resources/ceremonies/redirect-url) - Can I embed the signing interface in my app? Yes! (/docs/embedded/introduction) - Can I receive a notification when my envelope is completed? Yes! (/docs/api/webhooks) - Can I retrieve the signed document? Yes! (/docs/api/resources/envelopes/object#param-url-1) ## Concepts URL: https://signatureapi.com/docs/api/concepts Description: Learn the core concepts of SignatureAPI including envelopes, documents, recipients, ceremonies, and deliverables SignatureAPI organizes the document signing process around five core concepts: ```mermaid flowchart LR subgraph Envelope B[Documents] C[Recipients] end C -- review and sign Documents during --> D[Ceremony] D -- after completion generates --> E[Deliverable] ``` ## Envelope An Envelope (/docs/api/resources/envelopes/object) is a container that holds documents and recipients. It organizes and tracks the entire signing workflow from creation to completion. ## Documents Documents (/docs/api/resources/documents/object) are the files within an envelope that recipients need to review and sign. You can provide PDFs directly or generate documents from templates (/docs/api/resources/documents/templates) with dynamic data. ## Recipients Recipients (/docs/api/resources/recipients/object) are the people who interact with the envelope. Each recipient has a type (/docs/api/resources/recipients/object#types) (signer, approver, preparer, or automatic signer) that determines what actions they can perform. ## Ceremony A Ceremony (/docs/api/resources/ceremonies/object) is a guided session in which a recipient reviews the documents and performs their required actions, such as signing. Each recipient completes their own ceremony, and you can control the signing order (/docs/api/resources/envelopes/routing) (parallel or sequential). ## Deliverable After all recipients have completed (/docs/api/resources/recipients/lifecycle) their actions, the envelope is completed (/docs/api/resources/envelopes/lifecycle). A Deliverable (/docs/api/resources/deliverables/object) is then generated, containing the signed documents and an audit log. The deliverable is sent to the recipients and is available for download via the API. ## API Overview URL: https://signatureapi.com/docs/api/overview Description: Understand SignatureAPI's RESTful architecture, base URLs, HTTP methods, versioning, and response codes 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. ### Base URL The base URL is `https://api.signatureapi.com` for both test and live modes (/docs/api/test-mode). For example, to create an envelope, you do a `POST` request to `https://api.signatureapi.com/v1/envelopes`. ### 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. | ### 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. ## Authentication URL: https://signatureapi.com/docs/api/authentication Description: Learn how to authenticate your API requests with SignatureAPI SignatureAPI uses **API key authentication** to secure access to your account and ensure only authorized requests can create, modify, or access your envelopes and documents. ## How authentication works All API requests require authentication using an API key passed in the `X-API-Key` header. When you make a request, SignatureAPI validates your API key and determines which account and environment (test or live) the request should access. Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth. ## Getting your API key You can get a free test API key to try out SignatureAPI and set up your workflow: ### Sign Up Sign up (https://accounts.signatureapi.com/sign-up) for a free account on SignatureAPI. ### Get your API key Navigate to the SignatureAPI Dashboard (https://dashboard.signatureapi.com/settings/api-keys) and copy your test API key from the API Keys section. ## Making authenticated requests Include your API key in the `X-API-Key` header with every request. Here's how to authenticate when creating an envelope: ```json // POST https://api.signatureapi.com/v1/envelopes // X-API-Key: key_test_... // Content-Type: application/json { "title": "Employment Agreement", //... } ``` ## API key types SignatureAPI provides different API key types for different environments: | Key Type | Format | Purpose | |----------|---------|---------| | Test keys | `key_test_...` | Development and testing without real legal consequences | | Live keys | `key_live_...` | Production use with legally-binding documents | ### Test mode benefits Test API keys let you create test envelopes, perfect for trying out your workflows. Envelopes in test mode: * Don't send emails to recipients (you can preview them in your dashboard) * Are not legally-binding, so no legal obligations arise during testing * Are completely free to use * Have all the same API functionality as live mode Learn more about Test Mode (/docs/api/test-mode). ## Authentication errors When authentication fails, you'll receive specific error responses to help you diagnose the issue: ### Invalid API Key The API key provided is not valid or improperly formatted. ```json // HTTP/1.1 401 Unauthorized { "type": "https://signatureapi.com/docs/v1/errors/invalid-api-key", "title": "Invalid API Key", "status": 401, "detail": "Please provide a valid API key in the X-API-Key header." } ``` **Common causes:** - Missing or incomplete API key - API key not passed in the `X-API-Key` header - Typos in the API key value Learn more about Invalid API Key errors (/docs/v1/errors/invalid-api-key) ### Forbidden Access **HTTP Status Code: 403** Your API key is valid but doesn't have permission to access the requested resource. ```json // HTTP/1.1 403 Forbidden { "type": "https://signatureapi.com/docs/v1/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "The requested resource exists, and the API key is valid, but the API key does not have permission to access it." } ``` **Common causes:** - Using an API key from a different account - Insufficient permissions for the requested operation Learn more about Forbidden errors (/docs/v1/errors/forbidden) ### Test/Live Mode Mismatch **HTTP Status Code: 403** You're trying to access a resource with the wrong environment key (test vs live). ```json // HTTP/1.1 403 Forbidden { "type": "https://signatureapi.com/docs/v1/errors/mode-error", "title": "Mode Error", "status": 403, "detail": "You are trying to access a test-mode resource with a live API key. Please use a test API key." } ``` **Common causes:** - Using a test API key to access live resources - Using a live API key to access test resources Learn more about Mode errors (/docs/v1/errors/mode-error) ## Next steps Now that you understand authentication, you're ready to: - Create your first envelope (/docs/api/quickstart) using the API - Explore the API playground (/docs/api/playground) to test requests interactively ## Test Mode URL: https://signatureapi.com/docs/api/test-mode Description: Learn how to create safe, non-binding, test-mode envelopes When you sign up for SignatureAPI, you get a free test API key. Test API keys let you create test envelopes, great for trying out your workflows. ## Test envelopes don't send emails Don't be afraid of flooding your customer's inboxes with test emails. Emails from test envelopes don't get sent to recipients. But, you can inspect them in your Dashboard's Email view (https://dashboard.signatureapi.com/emails?mode=test). Image: Dashboard's Email View (/docs/images/test-email-section.png) Where you can see the email contents: Image: Email Detail (/docs/images/test-email-detail.png) ## Test envelopes are not legally-binding A notice watermark on documents in test envelopes makes them non-binding. Image: Test Watermark (/docs/images/test-watermark.png) ## Test envelopes are free We don't bill you for test envelopes. ## Test mode and live mode differences | | Test mode | Live mode | |---|---|---| | API key prefix | `key_test_` | `key_live_` | | Emails sent | No. Preview in Dashboard (https://dashboard.signatureapi.com/emails?mode=test). | Yes, to real recipients. | | Legally binding | No. Documents show a watermark. | Yes. | | Billing | Free | Counted toward your plan. | | Webhooks | Delivered to test endpoints | Delivered to live endpoints | You can use test mode and live mode at the same time. They are independent: test envelopes, webhooks, and senders are separate from live ones. ## Switch to live mode When you are ready to start sending legally-binding envelopes, go to the API Key section of your Dashboard (https://dashboard.signatureapi.com). Follow the instructions to create a live API key. Replace `key_test_` with your new `key_live_` key in your API calls. No other code changes are needed. ## Webhooks URL: https://signatureapi.com/docs/api/webhooks Description: Learn how to receive events in your webhook endpoint Use webhooks to receive real-time events from your SignatureAPI account, so your backend can respond to these events and act accordingly. Receiving webhook events is useful for handling asynchronous events such as when a recipient signs an envelope (/docs/api/resources/events/recipient-events#recipient-completed), an envelope is completed (/docs/api/resources/events/envelope-events#envelope-completed), a deliverable is generated (/docs/api/resources/events/deliverable-events#deliverable-generated), or an email to a recipient bounces (/docs/api/resources/events/recipient-events#recipient-soft-bounced). ## Setting Up Webhooks You can receive events by registering a webhook endpoint in the Dashboard (https://dashboard.signatureapi.com/settings/webhooks). You can register different webhook endpoints for test or live (/docs/api/test-mode) events and select the specific events (/docs/api/resources/events/envelope-events) to subscribe to for each endpoint. ## Events When an event happens, SignatureAPI creates a new Event object (/docs/api/resources/events/object). This is an example of an event object for a `recipient.completed` event: ```json { "id": "evt_4p2oouvNvjp1I9ckgqycH2", "type": "recipient.completed", "timestamp": "2025-12-31T15:00:01.999Z", "data": { "envelope_id": "e387553d-cbb7-4924-abd8-b2d89699e9b5", "envelope_metadata": { "customer_ref": "x9550501", "account_annual_revenue": "$4,500,000" }, "object_id": "re_7v7Sion0vqjJioYmwfZ9mf", "object_type": "recipient", "recipient_type": "signer" } } ``` Learn more about the different types of events (/docs/api/resources/events/envelope-events). ## Topic Filters If you want to use this feature, please contact support at support@signatureapi.com (mailto:support@signatureapi.com) By default, SignatureAPI delivers events for all envelopes, whether in test or live mode. To receive events only for specific envelopes at a webhook endpoint, use **topic filters**. When creating an envelope, you can specify up to 10 topics in the `topics` array of the Envelope object (/docs/api/resources/envelopes/object). Then, while setting up a webhook endpoint, list all the topics to receive events for those envelopes. ## Event Delivery SignatureAPI delivers the event via a `POST` request to your webhook endpoint, with the Event object (/docs/api/resources/events/object) as the JSON payload. Delivery is successful if your endpoint responds with a status code in the `2XX` range (200 to 299). Any other status code means the delivery failed. SignatureAPI does not guarantee the order of event delivery, so your endpoint should be able to handle events arriving out of order. ## Retries If your endpoint responds with a status code outside the `2XX` range, SignatureAPI will keep trying to deliver the event for up to 48 hours, using an exponential backoff strategy. If delivery fails consistently for several days, we will notify the account owner and may temporarily disable deliveries to the endpoint. ## Authentication Webhook notifications are secured with an HMAC signature included in the `webhook-signature` header, following the Standard Webhooks specification (https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md#verifying-webhook-authenticity). You can find the **Signing Secret** in the right column of the webhook endpoint definition: Standard Webhooks provides SDKs to simplify webhook verification. For example, to verify signatures in JavaScript or TypeScript (https://www.npmjs.com/package/standardwebhooks): ```javascript const wh = new Webhook(signing_secret); wh.verify(webhook_payload, webhook_headers); ``` Libraries are available for the following languages: JavaScript and TypeScript (https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries/javascript), Python (https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries/python), Java and Kotlin (https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries/java), Rust (https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries/rust), Go (https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries/go), Ruby (https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries/ruby), PHP (https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries/php), C# (https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries/csharp), and Elixir (https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries/elixir). ## Source IPs If your webhook endpoint is behind a firewall, allow traffic from the following IP addresses: ``` 44.228.126.217 50.112.21.217 52.24.126.164 54.148.139.208 2600:1f24:64:8000::/56 ``` ## Tools These tools can be useful for testing webhooks: - Webhook.site (https://webhook.site): Generates a random endpoint URL and lets you inspect POST requests sent to that endpoint. - ngrok (https://ngrok.com/): Sets up a tunnel from an internet-facing endpoint to your local machine, allowing you to process webhooks locally. ## Pagination URL: https://signatureapi.com/docs/api/pagination Description: Navigate paginated API responses using cursor-based pagination with next and previous links All endpoints that list objects provide support for pagination. Paginated responses return items in reverse chronological order, such that the most recently created object will be returned first on the list and the oldest will be returned last. The result includes a `links` object with a `previous` and a `next` property. Do a `GET` to the URLs in those properties to fetch the previous or next page of results. ### Attributes Paginated responses share a common structure using cursor-based pagination. Links to fetch the next and previous page of the paginated result. Treat these URLs as a opaque strings. Do not try to parse or construct it. ### links A pre-built absolute path URI for fetching the next page of results. If the value is `null`, this is the last page of results. A pre-built absolute path URI for fetching the previous page of results. If the value is `null`, this is the first page of results. An array of objects, sorted in reverse chronological order by creation date. ### Example ```json { "links": { "next": "https://api.signatureapi.com/v1/envelopes/?cursor=seq_0thJdKRhN4&limit=20", "previous": "https://api.signatureapi.com/v1/envelopes/?cursor=seq_7yNl3c0t&limit=20" }, "data": [ {...}, {...}, ... ] } ``` ## Rate Limiting URL: https://signatureapi.com/docs/api/rate-limiting Description: Understand API rate limits and how to handle throttled requests SignatureAPI enforces rate limits to ensure fair usage and platform stability. Rate limits are applied per API key. There are two components to rate limiting: - **Rate** is the sustained number of requests allowed per second. - **Burst** is the maximum number of requests that can be sent in a short spike before throttling kicks in. Once the burst is exhausted, requests are throttled to the sustained rate. ## Default limits | Metric | Limit | |--------|-------| | Rate | 10 requests/second | | Burst | 10 requests | ## Extended limits For higher-volume workloads, the extended plan increases both limits: | Metric | Limit | |--------|-------| | Rate | 1,000 requests/second | | Burst | 1,000 requests | To upgrade to extended limits, contact support (/support). ## Rate limit responses When you exceed the rate limit, the API returns a `429 Too Many Requests` response. ```json // HTTP/1.1 429 Too Many Requests { "type": "https://signatureapi.com/docs/v1/errors/too-many-requests", "title": "Too many requests", "status": 429, "detail": "The client is sending too many requests per second." } ``` ## Handling rate limits When you receive a `429` response, wait briefly before retrying. A simple approach: 1. Wait 1 second after receiving a `429` response. 2. Retry the request. 3. If you receive another `429`, double the wait time (2 seconds, then 4 seconds, and so on). 4. After 5 retries, stop and log the failure for investigation. ## Errors URL: https://signatureapi.com/docs/api/errors Description: Handle API errors with RFC 7807 problem details, HTTP status codes, and validation error responses SignatureAPI uses conventional HTTP response codes to indicate the success or failure of an API request. In general: - Codes in the `2XX` range indicate success. - Codes in the `4XX` range indicate problems with the request, like missing parameters. - Codes in the `5XX` range indicate problems with SignatureAPI servers. Errors messages conform to RFC 7807 (https://datatracker.ietf.org/doc/html/rfc7807) and use a Content-Type of `application/problem+json`. ## General Errors This payload is for `4XX` client errors, except validation errors, and `5XX` errors. A URL that identifies the problem type. Visit the URL to learn more about this problem. short, human-readable summary of the problem type The HTTP status code generated by the server for this occurrence of the problem A human-readable explanation specific to this occurrence of the problem. #### Example ```json { "type": "https://signatureapi.com/docs/v1/errors/invalid-api-key", "title": "Invalid API Key", "status": 401, "detail": "Please provide a valid API key in the X-API-Key header." } ``` ## Validation Errors This payload is for validation errors (along a `422` status code). A URL that identifies the problem type. Visit the URL to learn more about this problem. short, human-readable summary of the problem type The HTTP status code generated by the server for this occurrence of the problem. For validation errors, this value is always `422`. A human-readable list of specific validation errors. #### Example ```json { "type": "https://signatureapi.com/docs/v1/errors/validation-error", "title": "Validation Error", "status": 422, "errors": [ "documents[0].url protocol must be HTTPS", "recipients[0].email must be a valid email address" ] } ``` ## API Playground URL: https://signatureapi.com/docs/api/playground Explore our API effortlessly using the API Playground, directly accessible in your Dashboard. Your test API key (/docs/api/test-mode) comes preconfigured, allowing you to start experimenting within seconds of creating your free account (https://accounts.signatureapi.com/sign-up). With the API Playground, you can create envelopes, monitor the generated resources, and review the emails that are sent, all in real time. Image: SignatureAPI API Playground (/docs/images/playground.webp) ## SignatureAPI in Postman URL: https://signatureapi.com/docs/api/postman Description: Test SignatureAPI endpoints and explore code examples with our public Postman collection We publish a Postman Collection that you can use to test our API and generate envelopes with many of our features. ### Postman Collection -> Link: https://www.postman.com/signatureapi/signatureapi-public-workspace/collection/4b6izv8/signatureapi-collection This Postman collection showcases how to create envelopes and initiate the electronic signature process using SignatureAPI. This collection is frequently updated and currently includes the following examples: - **Place Positioning** - Create an envelope with placeholders - Create an envelope with fixed positions - **Document Templates** - Create an envelope with a docx template - **Languages** - Create an envelope with Spanish interface - **Timestamp formats** - Create an envelope with month-day-year format - Create an envelope with day/month/year format - **Timezones** - Create an envelope in UTC timezone - Create an envelope in Hong Kong timezone - **Temporary Upload** - Create an envelope with a temporary upload - **Embedded Ceremony** - Create an envelope and a recipient's ceremony - **Multiple Recipients** - Create an envelope with multiple recipients signing in parallel - Create an envelope with multiple recipients signing sequentially ## SignatureAPI OpenAPI Spec URL: https://signatureapi.com/docs/api/openapi Description: Download the SignatureAPI OpenAPI 3.1 specification and discover the API programmatically The complete SignatureAPI specification, in OpenAPI 3.1 (https://spec.openapis.org/oas/v3.1.0.html) format, is available at: ``` https://spec.signatureapi.com/openapi.yaml ``` The specification always reflects the currently deployed API. Use it to generate clients, power agent integrations, or explore the API surface. ## Programmatic discovery We also publish an RFC 9727 (https://www.rfc-editor.org/rfc/rfc9727) API catalog at: ``` https://signatureapi.com/.well-known/api-catalog ``` The catalog is an RFC 9264 (https://www.rfc-editor.org/rfc/rfc9264) linkset pointing to the OpenAPI specification, this documentation, and the status page (https://signatureapi.com/status). Tools and agents can use it to discover the API from the domain name alone. ## Envelope URL: https://signatureapi.com/docs/api/resources/envelopes/object Description: The envelope object and all its properties An envelope is a container that holds documents (/docs/api/resources/documents/object) to be sent to recipients (/docs/api/resources/recipients/object) for signature. It defines and manages the signing process for those documents. When an envelope is completed (/docs/api/resources/envelopes/lifecycle), a deliverable (/docs/api/resources/deliverables/object) is generated and sent to the recipients. ## Relationships An envelope: - Has one or more recipients (/docs/api/resources/recipients/object) (signers, approvers, preparers, or automatic signers) - Has one or more documents (/docs/api/resources/documents/object) (PDF or DOCX format) - Has one or more deliverables (/docs/api/resources/deliverables/object) generated upon completion ## Attributes The unique identifier of the envelope, in UUID format. The title of the envelope, displayed to recipients in emails and the signing ceremony. Must be between 1 and 500 characters. For an internal label that is not shown to recipients, use the `label` property instead. A custom label for internal identification. Labels are not shown to recipients. Unlike `title`, which recipients see, the label is for your team's use only. It can be updated at any time via the Update Envelope endpoint. Maximum 500 characters. Defaults to `null`. A custom message included in the signing request emails sent to recipients. Use it to provide context about what is being signed. Supports up to 2,000 characters. Accepts a subset of Markdown: - `**bold**` for bold text - `*italic*` for italic text - `\n\n` for paragraph breaks Defaults to `null`. The current status of the envelope in its lifecycle. - `processing`: The envelope is being prepared. Documents are validated and recipients are notified. - `in_progress`: The envelope has been sent to recipients and is waiting for all participants to complete. - `completed`: All recipients have completed their part. The deliverable may still be generating; the `deliverable.generated` event signals it is ready. - `failed`: An internal error occurred during processing. Failures are rare and trigger automatic alerts. - `canceled`: The signing process was intentionally stopped before completion. The typical progression is `processing` → `in_progress` → `completed`. Learn more about the envelope lifecycle (/docs/api/resources/envelopes/lifecycle). The mode of the envelope, which determines its legal status and billing. - `live`: Legally binding and billable. Created when using a live API key. - `test`: Not legally binding and free of charge. Created when using a test API key. The mode is set automatically based on the API key used to create the envelope and cannot be changed afterward. Customizes the visual appearance of the signing ceremony and recipient emails. Branding does not affect internal notifications or signed documents. Learn more about branding (/docs/api/resources/envelopes/branding). ### Branding The URL of the logo image displayed in the header of emails and the signing ceremony. Must be a PNG file uploaded to the Library. Defaults to `null`. Only files uploaded to your account's Library are accepted. Direct external URLs are not supported. The accent color applied to buttons in emails and the signing ceremony. Specified as a hex color code (for example, `#2463eb`). Defaults to `#2463eb`. The color must have a contrast ratio of at least 4.5:1 against white, following WCAG guidelines (https://www.w3.org/TR/WCAG21/). If the color does not meet this requirement, the API returns an error with a suggested compliant alternative. Additional customization for emails sent to recipients, including footer text and logo alignment. ### Email Branding Options The email address shown in the "From" field of emails sent to recipients. Defaults to `noreply@signatureapi.com`. A custom footer included at the bottom of all recipient emails for this envelope, after SignatureAPI's standard footer content. Use it for disclaimers, privacy notices, or contact information. Defaults to `null`. Supports a subset of Markdown: `**bold**`, `*italic*`, and `\n\n` for paragraph breaks. Maximum 10,000 characters. The horizontal alignment of the logo in recipient emails. Accepted values are `left`, `center`, and `right`. Defaults to `left`. Controls the order in which recipients receive and act on the envelope. - `sequential`: Recipients act one at a time, in the order listed. Each recipient must complete before the next is notified. This is the default. - `parallel`: All recipients are notified at the same time and can act in any order. Learn more about recipient routing (/docs/api/resources/envelopes/routing). The language used for the signing ceremony, recipient emails, and the audit log in deliverables. Supported values: `en` (English), `es` (Spanish), `fr` (French), `it` (Italian), `pt` (Portuguese), `de` (German), `zh` (Chinese Simplified), `hu` (Hungarian). If not specified, the account's default language is used. Learn more about language (/docs/api/resources/envelopes/language). The time zone applied to timestamps in the deliverable's audit log. Must be a valid IANA Time Zone Database identifier (for example, `America/New_York` or `Europe/London`). If not specified, the account's default time zone is used. Learn more about time zones (/docs/api/resources/envelopes/timezone). The date and time format used for timestamps in the deliverable's audit log. Uses MomentJS format tokens (for example, `MM/DD/YYYY HH:mm:ss`). If not specified, the account's default timestamp format is used. Learn more about timestamp formats (/docs/api/resources/envelopes/timestamp-format). The sender of the envelope. Sender information appears in emails sent to recipients, identifying who initiated the signing request. If omitted, the account's default sender name and email are used. ### Sender The name of the sender, displayed to recipients in emails and the signing ceremony. Maximum 500 characters. The email address of the sender, shown to recipients for reference. Maximum 320 characters. The organization name of the sender, displayed to recipients alongside the sender's name and email. Defaults to `null`. Maximum 500 characters. An array of up to 10 tags used to classify the envelope and filter webhook notifications. Each topic must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters per topic. Learn more about topics (/docs/api/resources/envelopes/topics). A set of up to 10 custom key-value pairs for attaching internal reference data to the envelope. Use metadata to link envelopes to records in your own systems. Keys: up to 32 characters (letters, digits, and underscores). Values: up to 1,000 characters. Do not store sensitive information as metadata. Learn more about metadata (/docs/api/resources/envelopes/metadata). The documents included in the envelope. An envelope can contain between 1 and 10 documents. Each document must be a publicly accessible PDF or DOCX file. Documents can include interactive places such as signature fields, text inputs, and checkboxes that recipients interact with during the signing ceremony. DOCX documents also support dynamic content via template data. ### PDF Document The unique identifier of the document. Document IDs start with `doc_`. The unique identifier of the envelope, in UUID format. A user-provided identifier for this document within the envelope. Must be unique within the envelope. Use the key to reference this document in other parts of the API. Only lowercase letters, numbers, and underscores are allowed. Must start with a letter. Maximum 32 characters. If not provided, a key is generated automatically. An optional display name for the document. When set, the title is shown to recipients during the signing ceremony and in deliverables. Defaults to `null` if not provided. Maximum 500 characters. The total number of pages in the document after processing. For DOCX templates, this reflects the page count after template data has been merged. The URL where the document or template file is located. The file must be publicly accessible. You can host files on Amazon S3, Google Cloud Storage, Azure Blob Storage, Cloudflare R2, and other services. You can also use the URL returned by the Create Upload (/docs/api/resources/uploads/create) endpoint. Learn more about your options in Document URL and Upload (/docs/api/resources/documents/url). The file format of the document. Determines which features are available. - `pdf`: Standard PDF file. Supports places via placeholders or fixed positions. - `docx`: Microsoft Word file. Supports template fields for dynamic content in addition to places. For PDF documents the format is `pdf`. ### fixed position The key of the place to position. Must match one of the `key` values in the document's `places` array. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The page number where the place is positioned. Page numbering starts at 1. The vertical distance from the top edge of the page to the bottom-left corner of the place, measured in points (1 point = 1/72 of an inch). For example, `360` places the field 5 inches from the top edge. The horizontal distance from the left edge of the page to the bottom-left corner of the place, measured in points (1 point = 1/72 of an inch). For example, `72` places the field 1 inch from the left edge. Areas within a document where a recipient provides input (such as a signature or text) or where a value is displayed automatically (such as a completion date). Each place has a `type` that determines its behavior. A place must be positioned using either a `[[place_key]]` placeholder in the document text or an entry in the `fixed_positions` array. Learn more about places (/docs/api/resources/places/object). ### signature place A location where the recipient, identified by `recipient_key`, draws or types their signature. A single recipient can have multiple signature places across different pages of a document. Specifies the type of place. For a signature place, the value must be `signature`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. The height of the signature place in points. The width is calculated automatically using a 5:2 ratio based on this height. Must be between 20 and 60. Defaults to 60. ### initials place A location where the recipient, identified by `recipient_key`, enters their initials. A single recipient can have multiple initials places across different pages of a document. Specifies the type of place. For an initials place, the value must be `initials`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. The height of the initials place in points. The width equals the height. Must be between 20 and 60. Defaults to 60. ### text place A read-only text value displayed at a specific location on the document. It is not interactive and does not require a recipient. Use this to pre-fill static information such as company names, reference numbers, or dates before the signing process begins. Specifies the type of place. For a text place, the value must be `text`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The text content to display on the document. This is a static value set when the envelope is created and cannot be changed by the recipient. Maximum length is 1000 characters. The font size in points. Must be between 1 and 144. The default is 12. The font color for this text place. Must be a six-digit hex color code with a leading `#`. Defaults to `#000000` (black). ### text input place A location where the recipient, identified by `recipient_key`, types free-form text. Supports input validation, placeholder text, and tooltip hints. Use `capture_as` to store the entered value in the envelope's captures. Specifies the type of place. For a text input place, the value must be `text_input`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. A key that stores the recipient's input in the envelope's `captures` object. When set, the value entered or selected by the recipient is saved under this key after the envelope is completed. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. Set to `null` to disable capture. A tooltip message displayed over the input text field during the signing ceremony. Learn more in Hints and Prompts (/docs/api/resources/places/text-input#hints-and-prompts). A placeholder message shown inside the input text field during the signing ceremony. Learn more in Hints and Prompts (/docs/api/resources/places/text-input#hints-and-prompts). Specifies whether the recipient must fill this field to complete the signing ceremony. Possible values are `required` or `optional`. The default is `required`. Defines the validation format for the user’s input. Accepted values: - `email` - `zipcode-us` - a custom regular expression, enclosed in `/`, for example: `/^[a-z0-9]{1,10}$/` Learn more in Format Validation (/docs/api/resources/places/text-input#format-validation). The message displayed when the user’s input does not match the required format. Learn more in Format Validation -> Adding a Custom Message (/docs/api/resources/places/text-input#adding-a-custom-message). The initial width of the text input field in points. The field may expand beyond this width during typing. Must be between 30 and 540. Defaults to 30. The font size in points. Must be between 6 and 12. Defaults to 12. ### boxed text input place A series of individual character boxes where the recipient, identified by `recipient_key`, enters text one character per box. Use this for structured data such as verification codes, ZIP codes, or the last four digits of an SSN. Use `capture_as` to store the entered value in the envelope's captures. Specifies the type of place. For a boxed text input place, the value must be `boxed_text_input`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. The number of individual character boxes to display. Must be between 1 and 100. Each box accepts a single character from the recipient. Specifies whether the recipient must fill all boxes to complete the signing ceremony. Possible values are `required` or `optional`. The default is `required`. A placeholder message shown inside the first box during the signing ceremony to guide the recipient. Learn more in Hints and Prompts (/docs/api/resources/places/boxed-text-input#hints-and-prompts). A tooltip message displayed over the boxed text input field during the signing ceremony. Learn more in Hints and Prompts (/docs/api/resources/places/boxed-text-input#hints-and-prompts). A key that stores the recipient's input in the envelope's `captures` object. When set, the value entered or selected by the recipient is saved under this key after the envelope is completed. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. Set to `null` to disable capture. The total width of the boxed input field in points. Must be between 30 and 540. The default is 30. The height of each individual box in points. The font size in points. Must be between 6 and 12. The default is 12. ### multiline text input place A location where the recipient, identified by `recipient_key`, enters text that spans multiple lines. Use this for comments, addresses, and longer descriptions. Use `capture_as` to store the entered value in the envelope's captures. Specifies the type of place. For a multi-line text input place, the value must be `multiline_text_input`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. Specifies whether the recipient must fill this field to complete the signing ceremony. Possible values are `required` or `optional`. The default is `required`. A placeholder message shown inside the input text field during the signing ceremony. Learn more in Hints and Prompts (/docs/api/resources/places/multiline-text-input#hints-and-prompts). A tooltip message displayed over the input text field during the signing ceremony. Learn more in Hints and Prompts (/docs/api/resources/places/multiline-text-input#hints-and-prompts). A key that stores the recipient's input in the envelope's `captures` object. When set, the value entered or selected by the recipient is saved under this key after the envelope is completed. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. Set to `null` to disable capture. The width of the multi-line text input place in points. Must be between 30 and 540. The default is 30. The number of lines for the multi-line text input field. Must be between 1 and 100. The line height in points. Must be greater than or equal to `font_size`. Must be between 6 and 72. The default is 12. The font size in points. Must be between 6 and 12. The default is 12. ### checkbox place A location where the recipient, identified by `recipient_key`, checks or unchecks a box. Use `capture_as` to store the checkbox value in the envelope's captures. Specifies the type of place. For a checkbox place, the value must be `checkbox`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. A key that stores the recipient's input in the envelope's `captures` object. When set, the value entered or selected by the recipient is saved under this key after the envelope is completed. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. Set to `null` to disable capture. The symbol to display in the checkbox when it is checked. Available options are `check` and `xmark`. The default is `check`. Specifies whether the recipient must check this box to complete the signing ceremony. Possible values are `required` or `optional`. The default is `optional`. The height of the checkbox in points. The width equals the height. Must be between 8 and 40. Defaults to 20. ### dropdown place A location where the recipient, identified by `recipient_key`, selects from a list of options. Options can be a custom list of label-value pairs or a predefined set such as country names or US state codes. Use `capture_as` to store the selected value in the envelope's captures. Specifies the type of place. For a dropdown place, the value must be `dropdown`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. The list of options available in the dropdown. Either an array of custom `label`/`value` pairs, or a string specifying a predefined option set such as `us_states_names` or `world_countries_names`. The pre-selected option when the dropdown is displayed. The display behavior of the dropdown. Possible values: `auto`, `select`, or `combobox`. Whether the recipient must select an option. Possible values: `required` or `optional`. A placeholder message shown inside the dropdown field during the signing ceremony. A tooltip message displayed when the user hovers over or focuses on the dropdown field. A key that stores the recipient's input in the envelope's `captures` object. When set, the value entered or selected by the recipient is saved under this key after the envelope is completed. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. Set to `null` to disable capture. The font size in points for the dropdown field. The width of the dropdown field in points. ### recipient completed date place Displays the date and time when the recipient, identified by `recipient_key`, completed their action on the envelope. Use `date_format` to control how the date is formatted. Specifies the type of place. For this kind of place, the value must be `recipient_completed_date`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. The date and time format using Moment.js syntax (https://momentjs.com/docs/#/displaying/format/). Common formats include `D MMM YYYY` (31 Dec 2025), `YYYY-MM-DD` (2025-12-31), and `MM/DD/YYYY` (12/31/2025). Defaults to `D MMM YYYY`. ### envelope completed date place Displays the date and time when the envelope was completed. The envelope completes when all recipients have finished their actions. Use `date_format` to control how the date is formatted. Specifies the type of place. For this kind of place, the value must be `envelope_completed_date`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The date and time format using Moment.js syntax (https://momentjs.com/docs/#/displaying/format/). Common formats include `D MMM YYYY` (31 Dec 2025), `YYYY-MM-DD` (2025-12-31), and `MM/DD/YYYY` (12/31/2025). Defaults to `D MMM YYYY`. ### recipient name place Displays the name of the recipient, identified by `recipient_key`, at a specific location on the document. The value is inserted automatically. This place is read-only and does not require any action from the recipient. Specifies the type of place. For this kind of place, the value must be `recipient_name`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. ### recipient email place Displays the email address of the recipient, identified by `recipient_key`, at a specific location on the document. The value is inserted automatically. This place is read-only and does not require any action from the recipient. Specifies the type of place. For this kind of place, the value must be `recipient_email`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. ### DOCX Document The unique identifier of the document. Document IDs start with `doc_`. The unique identifier of the envelope, in UUID format. A user-provided identifier for this document within the envelope. Must be unique within the envelope. Use the key to reference this document in other parts of the API. Only lowercase letters, numbers, and underscores are allowed. Must start with a letter. Maximum 32 characters. If not provided, a key is generated automatically. An optional display name for the document. When set, the title is shown to recipients during the signing ceremony and in deliverables. Defaults to `null` if not provided. Maximum 500 characters. The total number of pages in the document after processing. For DOCX templates, this reflects the page count after template data has been merged. The URL where the document or template file is located. The file must be publicly accessible. You can host files on Amazon S3, Google Cloud Storage, Azure Blob Storage, Cloudflare R2, and other services. You can also use the URL returned by the Create Upload (/docs/api/resources/uploads/create) endpoint. Learn more about your options in Document URL and Upload (/docs/api/resources/documents/url). The file format of the document. Determines which features are available. - `pdf`: Standard PDF file. Supports places via placeholders or fixed positions. - `docx`: Microsoft Word file. Supports template fields for dynamic content in addition to places. For DOCX documents the format is `docx`. Template data used to fill dynamic fields in a DOCX template. Each key corresponds to a `{{key}}` placeholder in the template file. Keys must be alphanumeric and at most 32 characters. Values can be strings, booleans, or nested objects. Nested keys map to dot-notation placeholders (for example, a key `person` with nested key `name` fills `{{person.name}}`). Defaults to `{}`. ### fixed position The key of the place to position. Must match one of the `key` values in the document's `places` array. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The page number where the place is positioned. Page numbering starts at 1. The vertical distance from the top edge of the page to the bottom-left corner of the place, measured in points (1 point = 1/72 of an inch). For example, `360` places the field 5 inches from the top edge. The horizontal distance from the left edge of the page to the bottom-left corner of the place, measured in points (1 point = 1/72 of an inch). For example, `72` places the field 1 inch from the left edge. Areas within a document where a recipient provides input (such as a signature or text) or where a value is displayed automatically (such as a completion date). Each place has a `type` that determines its behavior. A place must be positioned using either a `[[place_key]]` placeholder in the document text or an entry in the `fixed_positions` array. Learn more about places (/docs/api/resources/places/object). ### signature place A location where the recipient, identified by `recipient_key`, draws or types their signature. A single recipient can have multiple signature places across different pages of a document. Specifies the type of place. For a signature place, the value must be `signature`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. The height of the signature place in points. The width is calculated automatically using a 5:2 ratio based on this height. Must be between 20 and 60. Defaults to 60. ### initials place A location where the recipient, identified by `recipient_key`, enters their initials. A single recipient can have multiple initials places across different pages of a document. Specifies the type of place. For an initials place, the value must be `initials`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. The height of the initials place in points. The width equals the height. Must be between 20 and 60. Defaults to 60. ### text place A read-only text value displayed at a specific location on the document. It is not interactive and does not require a recipient. Use this to pre-fill static information such as company names, reference numbers, or dates before the signing process begins. Specifies the type of place. For a text place, the value must be `text`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The text content to display on the document. This is a static value set when the envelope is created and cannot be changed by the recipient. Maximum length is 1000 characters. The font size in points. Must be between 1 and 144. The default is 12. The font color for this text place. Must be a six-digit hex color code with a leading `#`. Defaults to `#000000` (black). ### text input place A location where the recipient, identified by `recipient_key`, types free-form text. Supports input validation, placeholder text, and tooltip hints. Use `capture_as` to store the entered value in the envelope's captures. Specifies the type of place. For a text input place, the value must be `text_input`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. A key that stores the recipient's input in the envelope's `captures` object. When set, the value entered or selected by the recipient is saved under this key after the envelope is completed. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. Set to `null` to disable capture. A tooltip message displayed over the input text field during the signing ceremony. Learn more in Hints and Prompts (/docs/api/resources/places/text-input#hints-and-prompts). A placeholder message shown inside the input text field during the signing ceremony. Learn more in Hints and Prompts (/docs/api/resources/places/text-input#hints-and-prompts). Specifies whether the recipient must fill this field to complete the signing ceremony. Possible values are `required` or `optional`. The default is `required`. Defines the validation format for the user’s input. Accepted values: - `email` - `zipcode-us` - a custom regular expression, enclosed in `/`, for example: `/^[a-z0-9]{1,10}$/` Learn more in Format Validation (/docs/api/resources/places/text-input#format-validation). The message displayed when the user’s input does not match the required format. Learn more in Format Validation -> Adding a Custom Message (/docs/api/resources/places/text-input#adding-a-custom-message). The initial width of the text input field in points. The field may expand beyond this width during typing. Must be between 30 and 540. Defaults to 30. The font size in points. Must be between 6 and 12. Defaults to 12. ### boxed text input place A series of individual character boxes where the recipient, identified by `recipient_key`, enters text one character per box. Use this for structured data such as verification codes, ZIP codes, or the last four digits of an SSN. Use `capture_as` to store the entered value in the envelope's captures. Specifies the type of place. For a boxed text input place, the value must be `boxed_text_input`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. The number of individual character boxes to display. Must be between 1 and 100. Each box accepts a single character from the recipient. Specifies whether the recipient must fill all boxes to complete the signing ceremony. Possible values are `required` or `optional`. The default is `required`. A placeholder message shown inside the first box during the signing ceremony to guide the recipient. Learn more in Hints and Prompts (/docs/api/resources/places/boxed-text-input#hints-and-prompts). A tooltip message displayed over the boxed text input field during the signing ceremony. Learn more in Hints and Prompts (/docs/api/resources/places/boxed-text-input#hints-and-prompts). A key that stores the recipient's input in the envelope's `captures` object. When set, the value entered or selected by the recipient is saved under this key after the envelope is completed. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. Set to `null` to disable capture. The total width of the boxed input field in points. Must be between 30 and 540. The default is 30. The height of each individual box in points. The font size in points. Must be between 6 and 12. The default is 12. ### multiline text input place A location where the recipient, identified by `recipient_key`, enters text that spans multiple lines. Use this for comments, addresses, and longer descriptions. Use `capture_as` to store the entered value in the envelope's captures. Specifies the type of place. For a multi-line text input place, the value must be `multiline_text_input`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. Specifies whether the recipient must fill this field to complete the signing ceremony. Possible values are `required` or `optional`. The default is `required`. A placeholder message shown inside the input text field during the signing ceremony. Learn more in Hints and Prompts (/docs/api/resources/places/multiline-text-input#hints-and-prompts). A tooltip message displayed over the input text field during the signing ceremony. Learn more in Hints and Prompts (/docs/api/resources/places/multiline-text-input#hints-and-prompts). A key that stores the recipient's input in the envelope's `captures` object. When set, the value entered or selected by the recipient is saved under this key after the envelope is completed. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. Set to `null` to disable capture. The width of the multi-line text input place in points. Must be between 30 and 540. The default is 30. The number of lines for the multi-line text input field. Must be between 1 and 100. The line height in points. Must be greater than or equal to `font_size`. Must be between 6 and 72. The default is 12. The font size in points. Must be between 6 and 12. The default is 12. ### checkbox place A location where the recipient, identified by `recipient_key`, checks or unchecks a box. Use `capture_as` to store the checkbox value in the envelope's captures. Specifies the type of place. For a checkbox place, the value must be `checkbox`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. A key that stores the recipient's input in the envelope's `captures` object. When set, the value entered or selected by the recipient is saved under this key after the envelope is completed. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. Set to `null` to disable capture. The symbol to display in the checkbox when it is checked. Available options are `check` and `xmark`. The default is `check`. Specifies whether the recipient must check this box to complete the signing ceremony. Possible values are `required` or `optional`. The default is `optional`. The height of the checkbox in points. The width equals the height. Must be between 8 and 40. Defaults to 20. ### dropdown place A location where the recipient, identified by `recipient_key`, selects from a list of options. Options can be a custom list of label-value pairs or a predefined set such as country names or US state codes. Use `capture_as` to store the selected value in the envelope's captures. Specifies the type of place. For a dropdown place, the value must be `dropdown`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. The list of options available in the dropdown. Either an array of custom `label`/`value` pairs, or a string specifying a predefined option set such as `us_states_names` or `world_countries_names`. The pre-selected option when the dropdown is displayed. The display behavior of the dropdown. Possible values: `auto`, `select`, or `combobox`. Whether the recipient must select an option. Possible values: `required` or `optional`. A placeholder message shown inside the dropdown field during the signing ceremony. A tooltip message displayed when the user hovers over or focuses on the dropdown field. A key that stores the recipient's input in the envelope's `captures` object. When set, the value entered or selected by the recipient is saved under this key after the envelope is completed. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. Set to `null` to disable capture. The font size in points for the dropdown field. The width of the dropdown field in points. ### recipient completed date place Displays the date and time when the recipient, identified by `recipient_key`, completed their action on the envelope. Use `date_format` to control how the date is formatted. Specifies the type of place. For this kind of place, the value must be `recipient_completed_date`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. The date and time format using Moment.js syntax (https://momentjs.com/docs/#/displaying/format/). Common formats include `D MMM YYYY` (31 Dec 2025), `YYYY-MM-DD` (2025-12-31), and `MM/DD/YYYY` (12/31/2025). Defaults to `D MMM YYYY`. ### envelope completed date place Displays the date and time when the envelope was completed. The envelope completes when all recipients have finished their actions. Use `date_format` to control how the date is formatted. Specifies the type of place. For this kind of place, the value must be `envelope_completed_date`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The date and time format using Moment.js syntax (https://momentjs.com/docs/#/displaying/format/). Common formats include `D MMM YYYY` (31 Dec 2025), `YYYY-MM-DD` (2025-12-31), and `MM/DD/YYYY` (12/31/2025). Defaults to `D MMM YYYY`. ### recipient name place Displays the name of the recipient, identified by `recipient_key`, at a specific location on the document. The value is inserted automatically. This place is read-only and does not require any action from the recipient. Specifies the type of place. For this kind of place, the value must be `recipient_name`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. ### recipient email place Displays the email address of the recipient, identified by `recipient_key`, at a specific location on the document. The value is inserted automatically. This place is read-only and does not require any action from the recipient. Specifies the type of place. For this kind of place, the value must be `recipient_email`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. The recipients who participate in the envelope's signing process. An envelope can have between 1 and 10 recipients. Four types are supported: - `signer`: Signs the documents. - `preparer`: Fills in fields before signers receive the documents. - `approver`: Reviews and approves the documents without signing. - `automatic_signer`: Has their signature applied automatically. ### Signer The unique identifier of the recipient. Recipient IDs use the `re_` prefix. The unique identifier of the envelope, in UUID format. The type of the recipient. Determines what actions the recipient can perform during the ceremony. TypeDescription signerSigns documents. Every envelope must have at least one signing recipient. approverReviews and approves documents without signing. preparerFills in document fields on behalf of another party. automatic_signerThe signature is applied automatically by the system. For signers, the type is `signer`. A unique identifier you assign to each recipient in the envelope. Use it to match recipients with the places they should interact with (such as signature fields) and to identify them in events and webhook notifications. The key must start with a lowercase letter. It can contain lowercase letters, numbers, and underscores. Maximum 32 characters. It must be unique within the envelope. The full name of the recipient. Appears in invitation emails and is pre-filled for typed signatures. The email address of the recipient. SignatureAPI emails the ceremony link to this address when the ceremony uses `email_link` authentication, and the completed deliverable when `delivery_type` is `email`. The current status of the recipient in the signing workflow. StatusDescription pendingThe envelope has not been sent to the recipient yet. This is the initial status. awaitingThe recipient is waiting for earlier recipients in the routing order to complete. sentThe invitation has been sent to the recipient. completedThe recipient has completed their required actions (for example, signed or approved). rejectedThe recipient declined to complete the envelope. soft_bouncedThe invitation email was temporarily undeliverable (for example, a full mailbox). You can resend the request. hard_bouncedThe invitation email was permanently undeliverable (for example, an invalid address). Use the Replace endpoint to assign a new recipient. failedAn error occurred and the invitation could not be sent. replacedThis recipient was replaced with a new one via the Replace endpoint. The current ceremony (/docs/api/resources/ceremonies/object) for the recipient. ### Ceremony ### Email Link Authentication With **email link authentication**, the recipient receives an email with a direct link to the ceremony. Clicking the link authenticates the recipient and opens the signing session. The type of authentication. Available values: `email_link`, `email_code`, and `custom`. For email link authentication, this value is `email_link`. The custom subject line used for this recipient's invitation email. `null` if the envelope title is used. The custom message body used for this recipient's invitation email. `null` if the envelope message is used. ### Email Code Authentication With **email code authentication**, the recipient receives an email from SignatureAPI containing a 9-digit code. The recipient must enter this code to authenticate and access the ceremony. The type of authentication. Available values: `email_link`, `email_code`, and `custom`. For email code authentication, this value is `email_code`. ### Custom Authentication With **custom authentication**, your application authenticates the recipient. SignatureAPI provides a ceremony URL that you share or embed in your application to give the recipient access. The type of authentication. Available values: `email_link`, `email_code`, and `custom`. For custom authentication, this value is `custom`. The name of your company or application that authenticated the recipient. This value appears in the envelope audit log as the authentication provider. Key-value pairs with metadata about the authentication event, such as timestamps, session IDs, and user identifiers. These values appear in the envelope audit log. The values in `data` must be sufficient to verify how the recipient was authenticated. You must retain all records needed to prove the recipient's authentication, such as session information. In cases such as legal proceedings, you may need to provide these records to confirm identity. Review our Terms & Conditions (/docs/legal/terms/terms) for details. An HTTPS URL to redirect the recipient to after the ceremony finishes. Learn more in Redirect URL (/docs/api/resources/ceremonies/redirect-url). The delay in seconds before the ceremony redirects to `redirect_url` (standalone ceremonies) or emits completion events (embedded ceremonies). Defaults to `3`. Allowed range: `0` to `20`. Learn more in Redirect URL (/docs/api/resources/ceremonies/redirect-url). The format of the ceremony URL. Available options: - `standard` (default): Full-length URL. Works for most use cases. - `short`: Shortened URL. Use this when sharing through space-constrained channels such as SMS or push notifications. Origins allowed to embed this ceremony in an iframe. These values set the `frame-ancestors` directive in the ceremony's Content Security Policy (CSP) header. Sources typically take the form of a scheme and host (for example, `https://app.example.com`). Wildcards are supported (for example, `https://*.example.com`). For all available options, see the frame-ancestors documentation (https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/frame-ancestors#sources). Defaults to an empty list (`[]`), which means embedding is not allowed. To allow embedding from all origins (not recommended for production), use `["*"]`. Only the origin (scheme and host) is used. Paths are ignored. The URL where the recipient can access the ceremony. You can share this link with the recipient directly or embed it in your application. This property is `null` when: - The ceremony uses `email_link` authentication. SignatureAPI delivers the URL by email in that case. - The ceremony is not active (for example, it is completed, revoked, or declined). The URL expires 30 days after creation, or when a new ceremony is created for the same recipient. Controls whether the completed deliverable is automatically emailed to this recipient. ValueDescription emailThe completed deliverable is delivered to this recipient by email. This is the default for signers. noneThe completed deliverable is not emailed. Your application is responsible for distributing the deliverable. The signature methods available to the signer. The first item in the array is shown as the default. OptionDescription typedThe signer types their name. It is pre-filled from the recipient's name property. drawnThe signer draws their signature using a mouse, stylus, or touchscreen. If not specified, both `typed` and `drawn` are available, with `typed` shown first. The time at which the recipient completed their required actions on the envelope (for example, signed or approved), in ISO 8601 format. Returns `null` if the recipient has not yet completed. The time at which the recipient's status last changed, in ISO 8601 format. Updates whenever the recipient transitions to a new status. ### Deprecated Fields How the ceremony is created for the recipient. Available options are `automatic` and `manual`. The default is `automatic`. This property is deprecated. Use the `ceremony` object on the recipient when creating an envelope to control ceremony creation. This property will continue to be supported for backwards compatibility. ### Preparer The unique identifier of the recipient. Recipient IDs use the `re_` prefix. The unique identifier of the envelope, in UUID format. The type of the recipient. Determines what actions the recipient can perform during the ceremony. TypeDescription signerSigns documents. Every envelope must have at least one signing recipient. approverReviews and approves documents without signing. preparerFills in document fields on behalf of another party. automatic_signerThe signature is applied automatically by the system. For preparers, the type is `preparer`. A unique identifier you assign to each recipient in the envelope. Use it to match recipients with the places they should interact with (such as signature fields) and to identify them in events and webhook notifications. The key must start with a lowercase letter. It can contain lowercase letters, numbers, and underscores. Maximum 32 characters. It must be unique within the envelope. The full name of the recipient. Appears in invitation emails and is pre-filled for typed signatures. The email address of the recipient. SignatureAPI emails the ceremony link to this address when the ceremony uses `email_link` authentication, and the completed deliverable when `delivery_type` is `email`. The current status of the recipient in the signing workflow. StatusDescription pendingThe envelope has not been sent to the recipient yet. This is the initial status. awaitingThe recipient is waiting for earlier recipients in the routing order to complete. sentThe invitation has been sent to the recipient. completedThe recipient has completed their required actions (for example, signed or approved). rejectedThe recipient declined to complete the envelope. soft_bouncedThe invitation email was temporarily undeliverable (for example, a full mailbox). You can resend the request. hard_bouncedThe invitation email was permanently undeliverable (for example, an invalid address). Use the Replace endpoint to assign a new recipient. failedAn error occurred and the invitation could not be sent. replacedThis recipient was replaced with a new one via the Replace endpoint. The current ceremony (/docs/api/resources/ceremonies/object) for the recipient. ### Ceremony ### Email Link Authentication With **email link authentication**, the recipient receives an email with a direct link to the ceremony. Clicking the link authenticates the recipient and opens the signing session. The type of authentication. Available values: `email_link`, `email_code`, and `custom`. For email link authentication, this value is `email_link`. The custom subject line used for this recipient's invitation email. `null` if the envelope title is used. The custom message body used for this recipient's invitation email. `null` if the envelope message is used. ### Email Code Authentication With **email code authentication**, the recipient receives an email from SignatureAPI containing a 9-digit code. The recipient must enter this code to authenticate and access the ceremony. The type of authentication. Available values: `email_link`, `email_code`, and `custom`. For email code authentication, this value is `email_code`. ### Custom Authentication With **custom authentication**, your application authenticates the recipient. SignatureAPI provides a ceremony URL that you share or embed in your application to give the recipient access. The type of authentication. Available values: `email_link`, `email_code`, and `custom`. For custom authentication, this value is `custom`. The name of your company or application that authenticated the recipient. This value appears in the envelope audit log as the authentication provider. Key-value pairs with metadata about the authentication event, such as timestamps, session IDs, and user identifiers. These values appear in the envelope audit log. The values in `data` must be sufficient to verify how the recipient was authenticated. You must retain all records needed to prove the recipient's authentication, such as session information. In cases such as legal proceedings, you may need to provide these records to confirm identity. Review our Terms & Conditions (/docs/legal/terms/terms) for details. An HTTPS URL to redirect the recipient to after the ceremony finishes. Learn more in Redirect URL (/docs/api/resources/ceremonies/redirect-url). The delay in seconds before the ceremony redirects to `redirect_url` (standalone ceremonies) or emits completion events (embedded ceremonies). Defaults to `3`. Allowed range: `0` to `20`. Learn more in Redirect URL (/docs/api/resources/ceremonies/redirect-url). The format of the ceremony URL. Available options: - `standard` (default): Full-length URL. Works for most use cases. - `short`: Shortened URL. Use this when sharing through space-constrained channels such as SMS or push notifications. Origins allowed to embed this ceremony in an iframe. These values set the `frame-ancestors` directive in the ceremony's Content Security Policy (CSP) header. Sources typically take the form of a scheme and host (for example, `https://app.example.com`). Wildcards are supported (for example, `https://*.example.com`). For all available options, see the frame-ancestors documentation (https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/frame-ancestors#sources). Defaults to an empty list (`[]`), which means embedding is not allowed. To allow embedding from all origins (not recommended for production), use `["*"]`. Only the origin (scheme and host) is used. Paths are ignored. The URL where the recipient can access the ceremony. You can share this link with the recipient directly or embed it in your application. This property is `null` when: - The ceremony uses `email_link` authentication. SignatureAPI delivers the URL by email in that case. - The ceremony is not active (for example, it is completed, revoked, or declined). The URL expires 30 days after creation, or when a new ceremony is created for the same recipient. Controls whether SignatureAPI emails the completed deliverable to the recipient once the envelope is finished. ValueDescription emailThe completed deliverable is delivered to this recipient by email. noneThe completed deliverable is not emailed. Your application is responsible for distributing the deliverable. This is the default for approvers and preparers. The time at which the recipient completed their required actions on the envelope (for example, signed or approved), in ISO 8601 format. Returns `null` if the recipient has not yet completed. The time at which the recipient's status last changed, in ISO 8601 format. Updates whenever the recipient transitions to a new status. ### Deprecated Fields How the ceremony is created for the recipient. Available options are `automatic` and `manual`. The default is `automatic`. This property is deprecated. Use the `ceremony` object on the recipient when creating an envelope to control ceremony creation. This property will continue to be supported for backwards compatibility. ### Approver The unique identifier of the recipient. Recipient IDs use the `re_` prefix. The unique identifier of the envelope, in UUID format. The type of the recipient. Determines what actions the recipient can perform during the ceremony. TypeDescription signerSigns documents. Every envelope must have at least one signing recipient. approverReviews and approves documents without signing. preparerFills in document fields on behalf of another party. automatic_signerThe signature is applied automatically by the system. For approvers, the type is `approver`. A unique identifier you assign to each recipient in the envelope. Use it to match recipients with the places they should interact with (such as signature fields) and to identify them in events and webhook notifications. The key must start with a lowercase letter. It can contain lowercase letters, numbers, and underscores. Maximum 32 characters. It must be unique within the envelope. The full name of the recipient. Appears in invitation emails and is pre-filled for typed signatures. The email address of the recipient. SignatureAPI emails the ceremony link to this address when the ceremony uses `email_link` authentication, and the completed deliverable when `delivery_type` is `email`. The current status of the recipient in the signing workflow. StatusDescription pendingThe envelope has not been sent to the recipient yet. This is the initial status. awaitingThe recipient is waiting for earlier recipients in the routing order to complete. sentThe invitation has been sent to the recipient. completedThe recipient has completed their required actions (for example, signed or approved). rejectedThe recipient declined to complete the envelope. soft_bouncedThe invitation email was temporarily undeliverable (for example, a full mailbox). You can resend the request. hard_bouncedThe invitation email was permanently undeliverable (for example, an invalid address). Use the Replace endpoint to assign a new recipient. failedAn error occurred and the invitation could not be sent. replacedThis recipient was replaced with a new one via the Replace endpoint. The current ceremony (/docs/api/resources/ceremonies/object) for the recipient. ### Ceremony ### Email Link Authentication With **email link authentication**, the recipient receives an email with a direct link to the ceremony. Clicking the link authenticates the recipient and opens the signing session. The type of authentication. Available values: `email_link`, `email_code`, and `custom`. For email link authentication, this value is `email_link`. The custom subject line used for this recipient's invitation email. `null` if the envelope title is used. The custom message body used for this recipient's invitation email. `null` if the envelope message is used. ### Email Code Authentication With **email code authentication**, the recipient receives an email from SignatureAPI containing a 9-digit code. The recipient must enter this code to authenticate and access the ceremony. The type of authentication. Available values: `email_link`, `email_code`, and `custom`. For email code authentication, this value is `email_code`. ### Custom Authentication With **custom authentication**, your application authenticates the recipient. SignatureAPI provides a ceremony URL that you share or embed in your application to give the recipient access. The type of authentication. Available values: `email_link`, `email_code`, and `custom`. For custom authentication, this value is `custom`. The name of your company or application that authenticated the recipient. This value appears in the envelope audit log as the authentication provider. Key-value pairs with metadata about the authentication event, such as timestamps, session IDs, and user identifiers. These values appear in the envelope audit log. The values in `data` must be sufficient to verify how the recipient was authenticated. You must retain all records needed to prove the recipient's authentication, such as session information. In cases such as legal proceedings, you may need to provide these records to confirm identity. Review our Terms & Conditions (/docs/legal/terms/terms) for details. An HTTPS URL to redirect the recipient to after the ceremony finishes. Learn more in Redirect URL (/docs/api/resources/ceremonies/redirect-url). The delay in seconds before the ceremony redirects to `redirect_url` (standalone ceremonies) or emits completion events (embedded ceremonies). Defaults to `3`. Allowed range: `0` to `20`. Learn more in Redirect URL (/docs/api/resources/ceremonies/redirect-url). The format of the ceremony URL. Available options: - `standard` (default): Full-length URL. Works for most use cases. - `short`: Shortened URL. Use this when sharing through space-constrained channels such as SMS or push notifications. Origins allowed to embed this ceremony in an iframe. These values set the `frame-ancestors` directive in the ceremony's Content Security Policy (CSP) header. Sources typically take the form of a scheme and host (for example, `https://app.example.com`). Wildcards are supported (for example, `https://*.example.com`). For all available options, see the frame-ancestors documentation (https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/frame-ancestors#sources). Defaults to an empty list (`[]`), which means embedding is not allowed. To allow embedding from all origins (not recommended for production), use `["*"]`. Only the origin (scheme and host) is used. Paths are ignored. The URL where the recipient can access the ceremony. You can share this link with the recipient directly or embed it in your application. This property is `null` when: - The ceremony uses `email_link` authentication. SignatureAPI delivers the URL by email in that case. - The ceremony is not active (for example, it is completed, revoked, or declined). The URL expires 30 days after creation, or when a new ceremony is created for the same recipient. Controls whether SignatureAPI emails the completed deliverable to the recipient once the envelope is finished. ValueDescription emailThe completed deliverable is delivered to this recipient by email. noneThe completed deliverable is not emailed. Your application is responsible for distributing the deliverable. This is the default for approvers and preparers. The time at which the recipient completed their required actions on the envelope (for example, signed or approved), in ISO 8601 format. Returns `null` if the recipient has not yet completed. The time at which the recipient's status last changed, in ISO 8601 format. Updates whenever the recipient transitions to a new status. ### Deprecated Fields How the ceremony is created for the recipient. Available options are `automatic` and `manual`. The default is `automatic`. This property is deprecated. Use the `ceremony` object on the recipient when creating an envelope to control ceremony creation. This property will continue to be supported for backwards compatibility. ### Automatic Signer The unique identifier of the recipient. Recipient IDs use the `re_` prefix. The unique identifier of the envelope, in UUID format. The type of the recipient. Determines what actions the recipient can perform during the ceremony. TypeDescription signerSigns documents. Every envelope must have at least one signing recipient. approverReviews and approves documents without signing. preparerFills in document fields on behalf of another party. automatic_signerThe signature is applied automatically by the system. For automatic signers, the type is `automatic_signer`. A unique identifier you assign to each recipient in the envelope. Use it to match recipients with the places they should interact with (such as signature fields) and to identify them in events and webhook notifications. The key must start with a lowercase letter. It can contain lowercase letters, numbers, and underscores. Maximum 32 characters. It must be unique within the envelope. The full name of the signer. Appears in the audit log line that records the automatic signature. The signature image applied to the document, as supplied at envelope creation. `null` if no preset signature was supplied. ### Preset symbol The symbol type. Currently only `drawn` is supported. The URL of the PNG upload referenced when the automatic signer was created. The initials image applied to the document, as supplied at envelope creation. `null` if no preset initials were supplied. Same shape as `signature`. A short statement explaining why the initiator was authorized to sign on behalf of this person. This string is shown as-is in the audit log. Maximum 500 characters. The current status of the recipient. An automatic signer transitions directly to `completed` once the envelope is released and the signature is applied. See recipient lifecycle (/docs/api/resources/recipients/lifecycle). The time at which the recipient's signature was applied, in ISO 8601 format. Returns `null` if the recipient has not yet completed. The time at which the recipient's status last changed, in ISO 8601 format. Automatic signers do not have `email`, `ceremony`, `delivery_type`, or `signature_options` properties. They do not receive invitations or access a ceremony. The regulatory attestation applied to the envelope. Use this to meet country-specific e-signature requirements. - `none`: No attestation. This is the default and covers most countries, including the US and EU member states. - `mx_nom151`: Mexico NOM-151 compliance. Attaches a preservation certificate to the deliverable. - `br_icp_brasil`: Brazil ICP-Brasil trusted timestamp. Embeds a timestamp in the deliverable. For more information, see Attestation (/docs/api/resources/envelopes/attestation). The deliverable that was automatically generated when the envelope was completed. ### Standard Deliverable The standard deliverable includes an audit log. To get signed documents without an audit log, use the simple deliverable (/docs/api/resources/deliverables/simple) instead. The unique identifier for this deliverable. A user-provided name for this deliverable. Use this to identify deliverables when an envelope has more than one. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Between 1 and 32 characters. The unique identifier of the envelope, in UUID format. The type of the deliverable. - `standard`: Includes the signed documents and an audit log with a certificate of completion. This is the default. - `simple`: Includes the signed documents only, without an audit log. For standard deliverables, the type is `standard`. The current status of the deliverable. - `pending`: The envelope is not yet completed. The deliverable is waiting to be generated. - `processing`: The envelope has completed and the deliverable is being generated. This usually takes a few seconds. - `generated`: The deliverable is ready. The `url` property contains a download link. - `failed`: The deliverable failed to generate. This is rare. SignatureAPI support is notified automatically. The URL for downloading the deliverable. `null` until the deliverable reaches `generated` status. By default, this is a pre-signed URL. It requires no additional authentication and expires after 1 hour. If the link has expired, retrieve the deliverable again to get a fresh URL. If your account uses authenticated URLs (for HIPAA compliance, for example), access this URL with your API key as you would any other API request. Authenticated URLs do not expire. The language for system-generated text in the audit log, including labels and the certificate of completion. Does not affect the content of the signed documents. Supported values: `en` (English), `es` (Spanish), `fr` (French), `it` (Italian), `pt` (Portuguese), `de` (German), `zh` (Chinese Simplified), `hu` (Hungarian). Defaults to the envelope language. The timezone used for timestamps in the audit log. Must be a valid IANA Time Zone Database identifier (e.g., `America/New_York`, `Europe/London`). Does not affect timestamps inside the signed documents. Defaults to the envelope timezone. The format for timestamps in the audit log. Uses MomentJS format tokens (e.g., `MM/DD/YYYY HH:mm:ss`). Does not affect timestamps inside the signed documents. Defaults to the envelope timestamp format. The keys of the documents to include in the deliverable. By default, all documents in the envelope are included. Use this to create a deliverable with only a subset of documents. For example, generate separate deliverables for different recipients. Accepts between 1 and 10 document keys. The password used to encrypt the deliverable. Recipients must enter this password to access the downloaded file. Password requirements: - Between 4 and 32 characters - Letters and numbers only (no special characters or spaces) When returned in API responses, the password value is masked for security (displayed as `********`). Password protection is available upon request. Contact support (/support) to enable this feature. The time the deliverable was created, in ISO 8601 format. Set when the envelope is created, or when a deliverable is created via the API. The time the deliverable was successfully generated, in ISO 8601 format. `null` until the deliverable reaches `generated` status. ### Simple Deliverable The simple deliverable does not include an audit log. To get signed documents with an audit log, use the standard deliverable (/docs/api/resources/deliverables/standard) instead. The unique identifier for this deliverable. A user-provided name for this deliverable. Use this to identify deliverables when an envelope has more than one. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Between 1 and 32 characters. The unique identifier of the envelope, in UUID format. The type of the deliverable. - `standard`: Includes the signed documents and an audit log with a certificate of completion. This is the default. - `simple`: Includes the signed documents only, without an audit log. For simple deliverables, the type is `simple`. The current status of the deliverable. - `pending`: The envelope is not yet completed. The deliverable is waiting to be generated. - `processing`: The envelope has completed and the deliverable is being generated. This usually takes a few seconds. - `generated`: The deliverable is ready. The `url` property contains a download link. - `failed`: The deliverable failed to generate. This is rare. SignatureAPI support is notified automatically. The URL for downloading the deliverable. `null` until the deliverable reaches `generated` status. By default, this is a pre-signed URL. It requires no additional authentication and expires after 1 hour. If the link has expired, retrieve the deliverable again to get a fresh URL. If your account uses authenticated URLs (for HIPAA compliance, for example), access this URL with your API key as you would any other API request. Authenticated URLs do not expire. The keys of the documents to include in the deliverable. By default, all documents in the envelope are included. Use this to create a deliverable with only a subset of documents. For example, generate separate deliverables for different recipients. Accepts between 1 and 10 document keys. The password used to encrypt the deliverable. Recipients must enter this password to access the downloaded file. Password requirements: - Between 4 and 32 characters - Letters and numbers only (no special characters or spaces) When returned in API responses, the password value is masked for security (displayed as `********`). Password protection is available upon request. Contact support (/support) to enable this feature. The time the deliverable was created, in ISO 8601 format. Set when the envelope is created, or when a deliverable is created via the API. The time the deliverable was successfully generated, in ISO 8601 format. `null` until the deliverable reaches `generated` status. Data captured from recipients during the signing ceremony. Each key corresponds to a `capture_as` identifier defined on a text input, checkbox, or dropdown place. Values are strings for text inputs, booleans for checkboxes, or `null` if not yet filled. Learn more about captures (/docs/api/resources/envelopes/captures). The URL to a PDF snapshot of the envelope, showing documents and signatures collected so far. Returns `null` unless the envelope meets all of the following criteria: - It uses sequential routing. - It is currently in progress (not `completed`). - It was created within 1 year. By default, this is a short-lived, pre-signed URL that requires no further authentication to download. The URL expires after 1 hour. If the link has expired, retrieve the envelope again to generate a new one. If you requested authenticated URLs (for example, to achieve HIPAA compliance), the URL must be accessed using the API key. Authenticated URLs do not expire. The time at which the envelope was created, in ISO 8601 format. The time at which all recipients completed the envelope, in ISO 8601 format. Returns `null` until the envelope reaches `completed` status. ```json Response { "id": "55072f0e-b919-4d69-89cd-e7e56af00530", "title": "Exploration Agreement", "label": "Exploration Agreement for Order Ref. 25005", "message": "Please review the agreement and provide your signature.", "status": "completed", "mode": "live", "routing": "sequential", "language": "en", "timezone": "America/New_York", "timestamp_format": "MM/DD/YYYY HH:mm:ss", "attestation": "none", "branding": { "logo": null, "accent_color": "#2463eb", "email": { "from": "noreply@signatureapi.com", "footer": null, "logo_position": "left" } }, "sender": { "name": "Jennifer Lee", "email": "jennifer@example.com", "organization": "Acme Enterprises" }, "topics": [ "sales", "project_blue" ], "metadata": { "customer_ref": "x9550501", "account_annual_revenue": "$4,500,000" }, "documents": [ { "id": "doc_3jBYlxa9gv0fGLzFAnfwxe", "envelope_id": "55072f0e-b919-4d69-89cd-e7e56af00530", "title": "Exploration Agreement", "page_count": 2, "url": "https://pub-e5051420e98a4fdfb3fd42a62fbf06fa.r2.dev/dummy.docx", "format": "docx", "data": { "date": "December 31st, 2025", "showAlert": true, "serviceProvider": { "name": "Jane Smith", "organization": "ACME Global, Inc." }, "client": { "name": "Michael J. Miller", "organization": "Miller Industries" } }, "places": [ { "key": "provider_signs_here", "type": "signature", "recipient_key": "service_provider" }, { "key": "client_signs_here", "type": "signature", "recipient_key": "client" } ] } ], "recipients": [ { "id": "re_26w2VVV5JVm4j459TY5BNM", "envelope_id": "55072f0e-b919-4d69-89cd-e7e56af00530", "type": "signer", "key": "service_provider", "name": "Jane Smith", "email": "jane@example.com", "status": "completed", "ceremony": { "authentication": [ { "type": "email_link", "subject_override": null, "message_override": null } ], "redirect_url": null, "redirect_delay": 3, "embeddable_in": [], "url_variant": "standard", "url": null }, "delivery_type": "email", "ceremony_creation": "automatic", "signature_options": ["typed", "drawn"], "completed_at": "2025-12-31T14:00:00.000Z", "status_updated_at": "2025-12-31T14:00:00.000Z" }, { "id": "re_38UVwrWdCqX5kqeKFJUTtf", "envelope_id": "55072f0e-b919-4d69-89cd-e7e56af00530", "type": "signer", "key": "client", "name": "Michael J. Miller", "email": "michael@example.com", "status": "completed", "ceremony": { "authentication": [ { "type": "email_link", "subject_override": null, "message_override": null } ], "redirect_url": null, "redirect_delay": 3, "embeddable_in": [], "url_variant": "standard", "url": null }, "delivery_type": "email", "ceremony_creation": "automatic", "signature_options": ["typed", "drawn"], "completed_at": "2025-12-31T15:00:00.000Z", "status_updated_at": "2025-12-31T15:00:00.000Z" } ], "deliverable": { "id": "del_1T7If8GgrTOf7zBVPaJf2e", "name": null, "envelope_id": "55072f0e-b919-4d69-89cd-e7e56af00530", "type": "standard", "status": "generated", "url": "https://s3.us-east-2.amazonaws.com/signatureapi-vault-dev/envelopes/55072f0e...", "language": "en", "timezone": "America/New_York", "timestamp_format": "MM/DD/YYYY HH:mm:ss", "included_documents": null, "password": null, "created_at": "2025-12-31T12:00:00.000Z", "generated_at": "2025-12-31T15:00:05.000Z" }, "captures": {}, "snapshot_url": null, "created_at": "2025-12-31T12:00:00.000Z", "completed_at": "2025-12-31T15:00:00.000Z" } ``` ## Envelope lifecycle URL: https://signatureapi.com/docs/api/resources/envelopes/lifecycle Description: Track envelope status through processing, in_progress, completed, failed, and canceled states The `status` property indicates the envelope's current stage in the signing process. | Status | Description | |--------|-------------| | `processing` | The envelope is being prepared. Documents are validated and recipients are queued for notification. | | `in_progress` | The envelope has been sent to recipients and is waiting for all participants to complete their part. | | `completed` | All recipients have completed the envelope. The deliverable may still be generating; the `deliverable.generated` event signals it is ready. | | `failed` | An internal error occurred during processing. Failures are rare and trigger automatic alerts to the support team. | | `canceled` | The signing process was stopped before completion. | The typical progression is `processing` to `in_progress` to `completed`. An envelope can transition to `failed` from `processing`, or to `canceled` from `in_progress`. To cancel an envelope in `in_progress` status, use the Cancel Envelope (/docs/api/resources/envelopes/cancel) endpoint. Envelopes in `processing` status cannot be canceled directly. They must first transition to `in_progress`. ## Envelope topics URL: https://signatureapi.com/docs/api/resources/envelopes/topics Description: Organize envelopes with tags and filter webhook notifications by topic Topics are tags you assign to envelopes. They serve two purposes: filtering webhook notifications and querying envelopes by category. You can assign up to 10 topics per envelope. Each topic must start with a lowercase letter and contain only lowercase letters, numbers, and underscores (maximum 32 characters). ## Assigning topics Set the `topics` property when creating an envelope: ```json // POST https://api.signatureapi.com/v1/envelopes // X-API-Key: key_test_... // Content-Type: application/json { "title": "Sales Contract", "topics": ["sales", "q1_2026"], "documents": [ //... ], "recipients": [ //... ] } ``` ## Filtering webhooks by topic Configure a webhook endpoint in the dashboard to receive events only for envelopes with specific topics. This lets you route different envelope types to different endpoints or trigger different workflows without building complex routing logic. For example, a company with separate finance and sales workflows can: 1. Tag finance envelopes with `finance` and sales envelopes with `sales`. 2. Configure one webhook endpoint to receive only `finance` events and another for `sales` events. 3. Each endpoint receives only the notifications relevant to its workflow. A webhook with no topic filter receives events for all envelopes. ## Filtering envelopes by topic Use the `topic` query parameter on the List Envelopes (/docs/api/resources/envelopes/list) endpoint to retrieve envelopes for a specific topic: ```json // GET https://api.signatureapi.com/v1/envelopes?topic=sales // X-API-Key: key_test_... ``` ## Topics vs. metadata Use topics to categorize and filter envelopes within SignatureAPI. Use metadata (/docs/api/resources/envelopes/metadata) to store information that connects envelopes to records in your own systems. ## Envelope metadata URL: https://signatureapi.com/docs/api/resources/envelopes/metadata Description: Attach custom key-value data to envelopes for internal reference IDs and tracking The `metadata` property lets you attach custom key-value pairs to an envelope. Use it to link envelopes to records in your own systems, such as internal reference IDs, account numbers, or transaction identifiers. Metadata is included in all API responses that return an envelope and in all webhook (/docs/api/webhooks) payloads in the `data.envelope_metadata` field. Do not store sensitive information (such as bank account numbers or card details) as metadata. ## Limits - Up to 10 key-value pairs per envelope. - Keys: up to 32 characters (letters, digits, and underscores). - Values: up to 1,000 characters. ## Using metadata Add a `metadata` object when creating an envelope: ```json // POST https://api.signatureapi.com/v1/envelopes // X-API-Key: key_test_... // Content-Type: application/json { "title": "Customer Agreement", "metadata": { "user_id": "100200", "contract_number": "CNT-2026-001" }, "documents": [ //... ], "recipients": [ //... ] } ``` When a recipient signs, SignatureAPI sends a `recipient.completed` webhook that includes your metadata: ```json { "id": "evt_4p2oouvNvjp1I9ckgqycH2", "type": "recipient.completed", "timestamp": "2025-12-31T15:00:01.999Z", "data": { "envelope_id": "e387553d-cbb7-4924-abd8-b2d89699e9b5", "envelope_metadata": { "user_id": "100200", "contract_number": "CNT-2026-001" } //... } } ``` Use the metadata in webhook handlers to update records, trigger workflows, or route notifications in your system. ## Examples ```json Multiple keys { "title": "Investment Agreement", "metadata": { "deal_id": "DEAL-2026-0042", "investor_id": "INV-88421", "round": "Series A", "amount": "500000" } //... } ``` ```json Webhook correlation { "title": "Loan Application", "metadata": { "application_id": "APP-78542", "correlation_id": "corr_a1b2c3d4", "source_system": "loan-origination" } //... } ``` ```json Customer reference { "title": "Service Agreement", "metadata": { "customer_id": "CUST-12345", "contract_number": "CNT-2026-001", "sales_rep": "jsmith" } //... } ``` ## Metadata vs. topics Use topics (/docs/api/resources/envelopes/topics) to categorize and filter envelopes within SignatureAPI. Use metadata to store information that connects envelopes to records in your own systems. ## Envelope branding URL: https://signatureapi.com/docs/api/resources/envelopes/branding Description: Add your company logo and accent colors to signing ceremonies and recipient emails Add your company's branding to individual envelopes to customize the signing ceremony interface and the emails sent to recipients. Each envelope can have its own branding configuration. Branding applies to: - The signing ceremony interface recipients see. - Emails sent to recipients throughout the signing process (signing requests and completed document delivery). Branding does not apply to: - Internal notification emails sent to the account owner. - Deliverables (signed documents). See the Visual examples (#visual-examples) section below for screenshots. ## Adding branding Include a `branding` object when creating an envelope: ```json // POST https://api.signatureapi.com/v1/envelopes // X-API-Key: key_test_... // Content-Type: application/json { "title": "Service Agreement", "documents": [ //... ], "recipients": [ //... ], "branding": { "logo": "https://api.signatureapi.com/v1/uploads/upl_3jBYlxa9gv0fGLzFAnfwxe", "accent_color": "#9810fa", "email": { "footer": "**Disclaimer:** This email and its attachments may contain confidential information. If you are not the intended recipient, please delete it and notify the sender.", "logo_position": "left" } } } ``` ## Accent colors The `accent_color` property sets the color of buttons in emails and the signing ceremony. Specify the color as a hex code (for example, `#9810fa`). The accent color applies only to button styles. Other interactive elements such as text input fields, checkboxes, and signature boxes keep their default colors (blue for normal states, red for error states). ### Accessibility requirements The accent color must meet a contrast ratio of at least 4.5:1 against white, following WCAG guidelines (https://www.w3.org/TR/WCAG21/). If the color does not meet this requirement, the API returns an error with a suggested compliant alternative. Test your color's contrast ratio using the WebAIM Color Contrast Checker (https://webaim.org/resources/contrastchecker/) before submitting. ## Logos The `logo` property sets the image displayed in the header of emails and the signing ceremony. ### Preparing your logo 1. Upload your logo to the Dashboard Library (https://dashboard.signatureapi.com/library). 2. Copy the resulting URL (it will look like `https://api.signatureapi.com/v1/uploads/upl_...`). 3. Use that URL in the `logo` property. Only files uploaded to your account's Library can be used as logos. Direct external URLs are not supported. ### Logo requirements - **Format:** PNG - **Height:** At least 160px to avoid pixelation on high-resolution displays - **File size:** Under 100KB - **Background:** Transparent works best, as logos appear against both white (emails) and gray (ceremony) backgrounds ## Email customization Use the `email` object within `branding` for additional email customization. ### Custom footer The `footer` property adds content at the bottom of all recipient emails, after SignatureAPI's standard footer. Use it for legal disclaimers, privacy notices, or contact information. The footer supports a subset of Markdown: `**bold**`, `*italic*`, and `\n\n` for paragraph breaks. ### Logo position The `logo_position` property controls the horizontal alignment of the logo in email headers. Accepted values are `left`, `center`, and `right`. The default is `left`. ## Visual examples The following screenshots show branding applied to a purple (`#9810fa`) envelope with a left-positioned logo. ### Signature request email Image: Signature request email with custom branding applied (/docs/images/purple-cloud-request.png) ### Signing ceremony interface Image: Signing ceremony interface with custom branding applied (/docs/images/purple-cloud-ceremony.png) ### Completed document delivery email Image: Document delivery email with custom branding applied (/docs/images/purple-cloud-deli.png) ## Language URL: https://signatureapi.com/docs/api/resources/envelopes/language Description: Set the language for signing interfaces and recipient emails with supported language codes The `language` property sets the language used for the signing ceremony, recipient emails, and the audit log in deliverables. Set it to one of the supported language codes when creating an envelope. If not specified, the account's default language is used. Set your account default in the Settings section of the dashboard. ## Supported languages | Language | Code | |----------|------| | English | `en` | | Spanish | `es` | | French | `fr` | | German | `de` | | Italian | `it` | | Portuguese (Brazil) | `pt` | | Chinese (Simplified) | `zh` | | Hungarian | `hu` | | Dutch | `nl` | More languages are coming soon. To ask about a specific language, contact support (/support). ## Setting the language for an envelope ```json // POST https://api.signatureapi.com/v1/envelopes // X-API-Key: key_test_... // Content-Type: application/json { "title": "Acuerdo de Ejemplo", "language": "es", "documents": [ //... ], "recipients": [ //... ] } ``` The selected language appears in: - Signing request and completion emails. - Buttons, messages, and click-through agreements in the ceremony interface. - The audit log in deliverables. ## Non-Latin scripts in documents The `language` property controls the signing interface and emails, not the document content. If your documents contain non-Latin scripts (Arabic, Hebrew, Chinese, etc.), the text renders correctly as long as the fonts are embedded in the file. - **PDF**: Fonts must be embedded in the PDF. Most PDF generators do this by default. If text appears garbled, re-export the PDF with fonts embedded. - **DOCX**: Embed fonts in the Word file before uploading. In Microsoft Word, go to **File > Options > Save** and check **Embed fonts in the file**. This ensures the document renders correctly regardless of what fonts are installed on the server. DOCX files created with Google Docs or LibreOffice may not embed fonts correctly. Use Microsoft Word for documents with non-Latin scripts. ## Time zone URL: https://signatureapi.com/docs/api/resources/envelopes/timezone Description: Configure time zones for deliverables at the account or envelope level The `timezone` property sets the time zone used for timestamps in the deliverable's audit log. It must be a valid IANA Time Zone Database (https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) identifier (for example, `America/New_York` or `Europe/London`). If not specified, the account's default time zone is used. Set your account default in the Settings section of the dashboard. ## Setting the time zone for an envelope ```json // POST https://api.signatureapi.com/v1/envelopes // X-API-Key: key_test_... // Content-Type: application/json { "title": "Service Agreement", "timezone": "Europe/London", "documents": [ //... ], "recipients": [ //... ] } ``` ## Common identifiers | Identifier | Region | |------------|--------| | `America/New_York` | US East Coast | | `America/Los_Angeles` | US West Coast | | `America/Chicago` | US Central | | `Europe/London` | United Kingdom | | `Europe/Paris` | Central Europe | | `Asia/Singapore` | Singapore | | `Australia/Sydney` | Eastern Australia | Use named identifiers (like `America/New_York`) rather than fixed offsets (like `Etc/GMT+5`). Named identifiers handle daylight saving changes automatically. ## Timestamp format URL: https://signatureapi.com/docs/api/resources/envelopes/timestamp-format Description: Customize the date and time format displayed in deliverables for your recipients The `timestamp_format` property controls how dates and times appear in the deliverable's audit log. It uses MomentJS format tokens. If not specified, the account's default timestamp format is used. Set your account default in the dashboard settings (https://dashboard.signatureapi.com/settings/general). ## Setting the timestamp format for an envelope ```json // POST https://api.signatureapi.com/v1/envelopes // X-API-Key: key_test_... // Content-Type: application/json { "title": "Service Agreement", "timestamp_format": "MM/DD/YYYY HH:mm:ss", "documents": [ //... ], "recipients": [ //... ] } ``` ## Format tokens Use these tokens to build a timestamp format string: | Token | Description | |-------|-------------| | `YYYY` | Year (four digits) | | `MM` | Month (two digits) | | `DD` | Day (two digits) | | `HH` | Hour (24-hour clock) | | `hh` | Hour (12-hour clock) | | `mm` | Minutes | | `ss` | Seconds | Supported date separators: `/`, `-`, `.`, or a space. Supported time separators: `:` or `.`. ## Common formats | Format | Example output | Common usage | |--------|----------------|--------------| | `MM/DD/YYYY HH:mm:ss` | 12/31/2025 23:59:59 | United States | | `DD/MM/YYYY HH:mm:ss` | 31/12/2025 23:59:59 | Europe, Australia | | `YYYY-MM-DD HH:mm:ss` | 2025-12-31 23:59:59 | ISO 8601 | | `MM/DD/YYYY hh:mm:ss` | 12/31/2025 11:59:59 PM | United States (12-hour) | | `DD.MM.YYYY HH:mm.ss` | 31.12.2025 23:59.59 | Germany, Eastern Europe | ## Attestation and compliance URL: https://signatureapi.com/docs/api/resources/envelopes/attestation Description: Meet legal e-signature requirements for ESIGN, UETA, eIDAS, and country-specific standards like Mexico NOM-151 and Brazil ICP-Brasil This page covers e-signature compliance. For HIPAA compliance (/docs/trust/compliance/hipaa) or SOC 2 compliance (/docs/trust/compliance/soc2), see their dedicated pages. SignatureAPI is legally binding and compliant with US e-signature regulations (ESIGN and UETA), the European eIDAS regulation (at the SES level), and similar laws around the world. Some countries have additional legal requirements. Use the `attestation` property to apply a country-specific standard to an envelope. ## Available attestations | Value | Description | |-------|-------------| | `none` | No attestation. This is the default and applies to most countries, including the US and EU member states. | | `mx_nom151` | Mexico NOM-151 (/docs/api/resources/envelopes/attestation/mexico-nom-151) compliance. Attaches a preservation certificate to the deliverable. | | `br_icp_brasil` | Brazil ICP-Brasil (/docs/api/resources/envelopes/attestation/brazil-icp-brasil) trusted timestamp. Embeds a timestamp in the deliverable. | ## Using an attestation Set the `attestation` property when creating the envelope: ```json // POST https://api.signatureapi.com/v1/envelopes // X-API-Key: key_test_... // Content-Type: application/json { "title": "Contrato", "attestation": "mx_nom151", "documents": [ //... ], "recipients": [ //... ] } ``` Attestations are applied when the envelope completes, as part of generating the deliverable. Attestations must be enabled for your account before use. Contact support (/support) to enable one. ## Mexico NOM-151 URL: https://signatureapi.com/docs/api/resources/envelopes/attestation/mexico-nom-151 Description: Comply with Mexico's NOM-151 standard by attaching a preservation certificate to your deliverables To enable NOM-151 attestations for your account, contact support (/support). NOM-151 (https://www.dof.gob.mx/normasOficiales/6499/seeco11_C/seeco11_C.html) defines the legal standards for data message preservation and document digitization in Mexico. When `attestation` is set to `mx_nom151`, a preservation certificate (constancia de conservación) in ASN.1 format is attached to the deliverable. SignatureAPI also adds a verification link on the last page of the deliverable. Both the certificate and the deliverable can be verified using any ASN.1 signature verification tool. To use NOM-151, set `attestation` to `mx_nom151` when creating the envelope: ```json // POST https://api.signatureapi.com/v1/envelopes // X-API-Key: key_test_... // Content-Type: application/json { "title": "Contrato", "attestation": "mx_nom151", "documents": [ //... ], "recipients": [ //... ] } ``` NOM-151 attestation adds $0.10 per completed envelope. ## Brazil ICP-Brasil URL: https://signatureapi.com/docs/api/resources/envelopes/attestation/brazil-icp-brasil Description: Comply with Brazil's MP 2.200-2/2001 by embedding an ICP-Brasil trusted timestamp in your deliverables To enable ICP-Brasil attestations for your account, contact support (/support). ICP-Brasil (Infraestrutura de Chaves Públicas Brasileira) is Brazil's national public key infrastructure, established by MP 2.200-2/2001 (https://www.planalto.gov.br/ccivil_03/mpv/antigas_2001/2200-2.htm). An ICP-Brasil trusted timestamp (carimbo do tempo) proves that a document existed, unaltered, at a specific point in time. When `attestation` is set to `br_icp_brasil`, SignatureAPI obtains an RFC 3161 timestamp from an ICP-Brasil accredited timestamp authority and embeds it in the deliverable as a PDF document timestamp. There is no extra page and no separate attachment: the timestamp is part of the deliverable itself. The timestamp is verifiable in standard PDF readers, such as Adobe Acrobat, under the document's signature panel. It includes long-term validation (LTV) data, so it remains verifiable even after the timestamp authority's certificates expire. To use ICP-Brasil, set `attestation` to `br_icp_brasil` when creating the envelope: ```json // POST https://api.signatureapi.com/v1/envelopes // X-API-Key: key_test_... // Content-Type: application/json { "title": "Contrato", "attestation": "br_icp_brasil", "documents": [ //... ], "recipients": [ //... ] } ``` ## Create an envelope URL: https://signatureapi.com/docs/api/resources/envelopes/create Description: Create a new envelope with documents and recipients to start the signing process Creates an envelope (/docs/api/resources/envelopes/object) and starts the signing process. The envelope begins in `processing` status while documents are validated and recipients are queued for notification. It transitions to `in_progress` once recipients are notified. At minimum, provide a `title`, at least one `document`, and at least one `recipient`. All other properties are optional. ## Body parameters ### Required #### `title` (string, required) The title of the envelope, displayed to recipients in emails and the signing ceremony. Must be between 1 and 500 characters. For an internal label that is not shown to recipients, use the `label` property instead. #### `documents` (array of documents, required) The documents included in the envelope. An envelope can contain between 1 and 10 documents. Each document must be a publicly accessible PDF or DOCX file. Documents can include interactive places such as signature fields, text inputs, and checkboxes that recipients interact with during the signing ceremony. DOCX documents also support dynamic content via template data. ### PDF Document A user-provided identifier for this document within the envelope. Must be unique within the envelope. Use the key to reference this document in other parts of the API. Only lowercase letters, numbers, and underscores are allowed. Must start with a letter. Maximum 32 characters. If not provided, a key is generated automatically. An optional display name for the document. When set, the title is shown to recipients during the signing ceremony and in deliverables. Defaults to `null` if not provided. Maximum 500 characters. The URL where the document or template file is located. The file must be publicly accessible. You can host files on Amazon S3, Google Cloud Storage, Azure Blob Storage, Cloudflare R2, and other services. You can also use the URL returned by the Create Upload (/docs/api/resources/uploads/create) endpoint. Learn more about your options in Document URL and Upload (/docs/api/resources/documents/url). The file format of the document. Determines which features are available. - `pdf`: Standard PDF file. Supports places via placeholders or fixed positions. - `docx`: Microsoft Word file. Supports template fields for dynamic content in addition to places. For PDF documents the format must be `pdf`. ### fixed position The key of the place to position. Must match one of the `key` values in the document's `places` array. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The page number where the place is positioned. Page numbering starts at 1. The vertical distance from the top edge of the page to the bottom-left corner of the place, measured in points (1 point = 1/72 of an inch). For example, `360` places the field 5 inches from the top edge. The horizontal distance from the left edge of the page to the bottom-left corner of the place, measured in points (1 point = 1/72 of an inch). For example, `72` places the field 1 inch from the left edge. Areas within a document where a recipient provides input (such as a signature or text) or where a value is displayed automatically (such as a completion date). Each place has a `type` that determines its behavior. A place must be positioned using either a `[[place_key]]` placeholder in the document text or an entry in the `fixed_positions` array. Learn more about places (/docs/api/resources/places/object). ### signature place A location where the recipient, identified by `recipient_key`, draws or types their signature. A single recipient can have multiple signature places across different pages of a document. Specifies the type of place. For a signature place, the value must be `signature`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. The height of the signature place in points. The width is calculated automatically using a 5:2 ratio based on this height. Must be between 20 and 60. Defaults to 60. ### initials place A location where the recipient, identified by `recipient_key`, enters their initials. A single recipient can have multiple initials places across different pages of a document. Specifies the type of place. For an initials place, the value must be `initials`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. The height of the initials place in points. The width equals the height. Must be between 20 and 60. Defaults to 60. ### text place A read-only text value displayed at a specific location on the document. It is not interactive and does not require a recipient. Use this to pre-fill static information such as company names, reference numbers, or dates before the signing process begins. Specifies the type of place. For a text place, the value must be `text`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The text content to display on the document. This is a static value set when the envelope is created and cannot be changed by the recipient. Maximum length is 1000 characters. The font size in points. Must be between 1 and 144. The default is 12. The font color for this text place. Must be a six-digit hex color code with a leading `#`. Defaults to `#000000` (black). ### text input place A location where the recipient, identified by `recipient_key`, types free-form text. Supports input validation, placeholder text, and tooltip hints. Use `capture_as` to store the entered value in the envelope's captures. Specifies the type of place. For a text input place, the value must be `text_input`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. A key that stores the recipient's input in the envelope's `captures` object. When set, the value entered or selected by the recipient is saved under this key after the envelope is completed. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. Set to `null` to disable capture. A tooltip message displayed over the input text field during the signing ceremony. Learn more in Hints and Prompts (/docs/api/resources/places/text-input#hints-and-prompts). A placeholder message shown inside the input text field during the signing ceremony. Learn more in Hints and Prompts (/docs/api/resources/places/text-input#hints-and-prompts). Specifies whether the recipient must fill this field to complete the signing ceremony. Possible values are `required` or `optional`. The default is `required`. Defines the validation format for the user’s input. Accepted values: - `email` - `zipcode-us` - a custom regular expression, enclosed in `/`, for example: `/^[a-z0-9]{1,10}$/` Learn more in Format Validation (/docs/api/resources/places/text-input#format-validation). The message displayed when the user’s input does not match the required format. Learn more in Format Validation -> Adding a Custom Message (/docs/api/resources/places/text-input#adding-a-custom-message). The initial width of the text input field in points. The field may expand beyond this width during typing. Must be between 30 and 540. Defaults to 30. The font size in points. Must be between 6 and 12. Defaults to 12. ### boxed text input place A series of individual character boxes where the recipient, identified by `recipient_key`, enters text one character per box. Use this for structured data such as verification codes, ZIP codes, or the last four digits of an SSN. Use `capture_as` to store the entered value in the envelope's captures. Specifies the type of place. For a boxed text input place, the value must be `boxed_text_input`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. The number of individual character boxes to display. Must be between 1 and 100. Each box accepts a single character from the recipient. A key that stores the recipient's input in the envelope's `captures` object. When set, the value entered or selected by the recipient is saved under this key after the envelope is completed. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. Set to `null` to disable capture. A tooltip message displayed over the boxed text input field during the signing ceremony. Learn more in Hints and Prompts (/docs/api/resources/places/boxed-text-input#hints-and-prompts). A placeholder message shown inside the first box during the signing ceremony to guide the recipient. Learn more in Hints and Prompts (/docs/api/resources/places/boxed-text-input#hints-and-prompts). Specifies whether the recipient must fill all boxes to complete the signing ceremony. Possible values are `required` or `optional`. The default is `required`. The total width of the boxed input field in points. Must be between 30 and 540. The default is 30. The height of each individual box in points. The font size in points. Must be between 6 and 12. The default is 12. ### multiline text input place A location where the recipient, identified by `recipient_key`, enters text that spans multiple lines. Use this for comments, addresses, and longer descriptions. Use `capture_as` to store the entered value in the envelope's captures. Specifies the type of place. For a multi-line text input place, the value must be `multiline_text_input`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. A key that stores the recipient's input in the envelope's `captures` object. When set, the value entered or selected by the recipient is saved under this key after the envelope is completed. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. Set to `null` to disable capture. A tooltip message displayed over the input text field during the signing ceremony. Learn more in Hints and Prompts (/docs/api/resources/places/multiline-text-input#hints-and-prompts). A placeholder message shown inside the input text field during the signing ceremony. Learn more in Hints and Prompts (/docs/api/resources/places/multiline-text-input#hints-and-prompts). Specifies whether the recipient must fill this field to complete the signing ceremony. Possible values are `required` or `optional`. The default is `required`. The width of the multi-line text input place in points. Must be between 30 and 540. The default is 30. The number of lines for the multi-line text input field. Must be between 1 and 100. The line height in points. Must be greater than or equal to `font_size`. Must be between 6 and 72. The default is 12. The font size in points. Must be between 6 and 12. The default is 12. ### checkbox place A location where the recipient, identified by `recipient_key`, checks or unchecks a box. Use `capture_as` to store the checkbox value in the envelope's captures. Specifies the type of place. For a checkbox place, the value must be `checkbox`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. A key that stores the recipient's input in the envelope's `captures` object. When set, the value entered or selected by the recipient is saved under this key after the envelope is completed. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. Set to `null` to disable capture. The symbol to display in the checkbox when it is checked. Available options are `check` and `xmark`. The default is `check`. Specifies whether the recipient must check this box to complete the signing ceremony. Possible values are `required` or `optional`. The default is `optional`. The height of the checkbox in points. The width equals the height. Must be between 8 and 40. Defaults to 20. ### dropdown place A location where the recipient, identified by `recipient_key`, selects from a list of options. Options can be a custom list of label-value pairs or a predefined set such as country names or US state codes. Use `capture_as` to store the selected value in the envelope's captures. Specifies the type of place. For a dropdown place, the value must be `dropdown`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. Specifies the list of options available in the dropdown. You can provide either **custom options** or a **predefined option set**. **Custom options**: An array of objects, each with a `label` (displayed to the user) and an optional `value` (captured when selected). If `value` is omitted, the `label` is used as the value. ```json "options": [ { "label": "Option A", "value": "a" }, { "label": "Option B", "value": "b" } ] ``` **Predefined options**: A string specifying a built-in option set: ValueDescription world_countries_namesCountry names (e.g., "United States", "Canada") world_countries_2_letter_codesISO 3166-1 alpha-2 codes (e.g., "US", "CA") world_countries_3_letter_codesISO 3166-1 alpha-3 codes (e.g., "USA", "CAN") world_countries_numeric_codesISO 3166-1 numeric codes (e.g., "840", "124") us_states_namesUS state names (e.g., "California", "Texas") us_states_2_letter_codesUS state codes (e.g., "CA", "TX") Specifies the option that is pre-selected when the dropdown is displayed. The value is first matched against the `label` of each option. If no match is found, it is matched against the `value` of each option. If no match is found, a validation error is returned. Specifies the behavior of the dropdown during the signing ceremony. Possible values: - `auto` (default): Automatically selects the best behavior based on the number of options. Uses `select` for 10 or fewer options, and `combobox` for more than 10 options. - `select`: Displays a standard dropdown list. Best for short lists where users can quickly scan all options. - `combobox`: Displays a searchable dropdown with type-ahead filtering. Best for long lists where users need to search for their selection. Specifies whether the recipient must select an option to complete the signing ceremony. Possible values are `required` or `optional`. The default is `required`. A placeholder message shown inside the dropdown field during the signing ceremony. Maximum length is 100 characters. Learn more in Hints and Prompts (/docs/api/resources/places/dropdown#hints-and-prompts). A tooltip message displayed when the user hovers over or focuses on the dropdown field during the signing ceremony. Maximum length is 100 characters. Learn more in Hints and Prompts (/docs/api/resources/places/dropdown#hints-and-prompts). A key that stores the recipient's input in the envelope's `captures` object. When set, the value entered or selected by the recipient is saved under this key after the envelope is completed. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. Set to `null` to disable capture. The font size in points. Must be between 6 and 12. The default is 12. The width of the dropdown field in points. Must be between 30 and 540. The default is 30. ### recipient completed date place Displays the date and time when the recipient, identified by `recipient_key`, completed their action on the envelope. Use `date_format` to control how the date is formatted. Specifies the type of place. For this kind of place, the value must be `recipient_completed_date`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. The date and time format using Moment.js syntax (https://momentjs.com/docs/#/displaying/format/). Common formats include `D MMM YYYY` (31 Dec 2025), `YYYY-MM-DD` (2025-12-31), and `MM/DD/YYYY` (12/31/2025). Defaults to `D MMM YYYY`. The font size in points. Must be between 1 and 144. Defaults to 12. ### envelope completed date place Displays the date and time when the envelope was completed. The envelope completes when all recipients have finished their actions. Use `date_format` to control how the date is formatted. Specifies the type of place. For this kind of place, the value must be `envelope_completed_date`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The date and time format using Moment.js syntax (https://momentjs.com/docs/#/displaying/format/). Common formats include `D MMM YYYY` (31 Dec 2025), `YYYY-MM-DD` (2025-12-31), and `MM/DD/YYYY` (12/31/2025). Defaults to `D MMM YYYY`. The font size in points. Must be between 1 and 144. Defaults to 12. ### recipient name place Displays the name of the recipient, identified by `recipient_key`, at a specific location on the document. The value is inserted automatically. This place is read-only and does not require any action from the recipient. Specifies the type of place. For this kind of place, the value must be `recipient_name`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. The font size in points. Must be between 1 and 144. Defaults to 12. ### recipient email place Displays the email address of the recipient, identified by `recipient_key`, at a specific location on the document. The value is inserted automatically. This place is read-only and does not require any action from the recipient. Specifies the type of place. For this kind of place, the value must be `recipient_email`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. The font size in points. Must be between 1 and 144. Defaults to 12. ### DOCX Document A user-provided identifier for this document within the envelope. Must be unique within the envelope. Use the key to reference this document in other parts of the API. Only lowercase letters, numbers, and underscores are allowed. Must start with a letter. Maximum 32 characters. If not provided, a key is generated automatically. An optional display name for the document. When set, the title is shown to recipients during the signing ceremony and in deliverables. Defaults to `null` if not provided. Maximum 500 characters. The URL where the document or template file is located. The file must be publicly accessible. You can host files on Amazon S3, Google Cloud Storage, Azure Blob Storage, Cloudflare R2, and other services. You can also use the URL returned by the Create Upload (/docs/api/resources/uploads/create) endpoint. Learn more about your options in Document URL and Upload (/docs/api/resources/documents/url). The file format of the document. Determines which features are available. - `pdf`: Standard PDF file. Supports places via placeholders or fixed positions. - `docx`: Microsoft Word file. Supports template fields for dynamic content in addition to places. For DOCX documents the format must be `docx`. Template data used to fill dynamic fields in a DOCX template. Each key corresponds to a `{{key}}` placeholder in the template file. Keys must be alphanumeric and at most 32 characters. Values can be strings, booleans, or nested objects. Nested keys map to dot-notation placeholders (for example, a key `person` with nested key `name` fills `{{person.name}}`). Defaults to `{}`. ### fixed position The key of the place to position. Must match one of the `key` values in the document's `places` array. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The page number where the place is positioned. Page numbering starts at 1. The vertical distance from the top edge of the page to the bottom-left corner of the place, measured in points (1 point = 1/72 of an inch). For example, `360` places the field 5 inches from the top edge. The horizontal distance from the left edge of the page to the bottom-left corner of the place, measured in points (1 point = 1/72 of an inch). For example, `72` places the field 1 inch from the left edge. Areas within a document where a recipient provides input (such as a signature or text) or where a value is displayed automatically (such as a completion date). Each place has a `type` that determines its behavior. A place must be positioned using either a `[[place_key]]` placeholder in the document text or an entry in the `fixed_positions` array. Learn more about places (/docs/api/resources/places/object). ### signature place A location where the recipient, identified by `recipient_key`, draws or types their signature. A single recipient can have multiple signature places across different pages of a document. Specifies the type of place. For a signature place, the value must be `signature`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. The height of the signature place in points. The width is calculated automatically using a 5:2 ratio based on this height. Must be between 20 and 60. Defaults to 60. ### initials place A location where the recipient, identified by `recipient_key`, enters their initials. A single recipient can have multiple initials places across different pages of a document. Specifies the type of place. For an initials place, the value must be `initials`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. The height of the initials place in points. The width equals the height. Must be between 20 and 60. Defaults to 60. ### text place A read-only text value displayed at a specific location on the document. It is not interactive and does not require a recipient. Use this to pre-fill static information such as company names, reference numbers, or dates before the signing process begins. Specifies the type of place. For a text place, the value must be `text`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The text content to display on the document. This is a static value set when the envelope is created and cannot be changed by the recipient. Maximum length is 1000 characters. The font size in points. Must be between 1 and 144. The default is 12. The font color for this text place. Must be a six-digit hex color code with a leading `#`. Defaults to `#000000` (black). ### text input place A location where the recipient, identified by `recipient_key`, types free-form text. Supports input validation, placeholder text, and tooltip hints. Use `capture_as` to store the entered value in the envelope's captures. Specifies the type of place. For a text input place, the value must be `text_input`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. A key that stores the recipient's input in the envelope's `captures` object. When set, the value entered or selected by the recipient is saved under this key after the envelope is completed. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. Set to `null` to disable capture. A tooltip message displayed over the input text field during the signing ceremony. Learn more in Hints and Prompts (/docs/api/resources/places/text-input#hints-and-prompts). A placeholder message shown inside the input text field during the signing ceremony. Learn more in Hints and Prompts (/docs/api/resources/places/text-input#hints-and-prompts). Specifies whether the recipient must fill this field to complete the signing ceremony. Possible values are `required` or `optional`. The default is `required`. Defines the validation format for the user’s input. Accepted values: - `email` - `zipcode-us` - a custom regular expression, enclosed in `/`, for example: `/^[a-z0-9]{1,10}$/` Learn more in Format Validation (/docs/api/resources/places/text-input#format-validation). The message displayed when the user’s input does not match the required format. Learn more in Format Validation -> Adding a Custom Message (/docs/api/resources/places/text-input#adding-a-custom-message). The initial width of the text input field in points. The field may expand beyond this width during typing. Must be between 30 and 540. Defaults to 30. The font size in points. Must be between 6 and 12. Defaults to 12. ### boxed text input place A series of individual character boxes where the recipient, identified by `recipient_key`, enters text one character per box. Use this for structured data such as verification codes, ZIP codes, or the last four digits of an SSN. Use `capture_as` to store the entered value in the envelope's captures. Specifies the type of place. For a boxed text input place, the value must be `boxed_text_input`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. The number of individual character boxes to display. Must be between 1 and 100. Each box accepts a single character from the recipient. A key that stores the recipient's input in the envelope's `captures` object. When set, the value entered or selected by the recipient is saved under this key after the envelope is completed. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. Set to `null` to disable capture. A tooltip message displayed over the boxed text input field during the signing ceremony. Learn more in Hints and Prompts (/docs/api/resources/places/boxed-text-input#hints-and-prompts). A placeholder message shown inside the first box during the signing ceremony to guide the recipient. Learn more in Hints and Prompts (/docs/api/resources/places/boxed-text-input#hints-and-prompts). Specifies whether the recipient must fill all boxes to complete the signing ceremony. Possible values are `required` or `optional`. The default is `required`. The total width of the boxed input field in points. Must be between 30 and 540. The default is 30. The height of each individual box in points. The font size in points. Must be between 6 and 12. The default is 12. ### multiline text input place A location where the recipient, identified by `recipient_key`, enters text that spans multiple lines. Use this for comments, addresses, and longer descriptions. Use `capture_as` to store the entered value in the envelope's captures. Specifies the type of place. For a multi-line text input place, the value must be `multiline_text_input`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. A key that stores the recipient's input in the envelope's `captures` object. When set, the value entered or selected by the recipient is saved under this key after the envelope is completed. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. Set to `null` to disable capture. A tooltip message displayed over the input text field during the signing ceremony. Learn more in Hints and Prompts (/docs/api/resources/places/multiline-text-input#hints-and-prompts). A placeholder message shown inside the input text field during the signing ceremony. Learn more in Hints and Prompts (/docs/api/resources/places/multiline-text-input#hints-and-prompts). Specifies whether the recipient must fill this field to complete the signing ceremony. Possible values are `required` or `optional`. The default is `required`. The width of the multi-line text input place in points. Must be between 30 and 540. The default is 30. The number of lines for the multi-line text input field. Must be between 1 and 100. The line height in points. Must be greater than or equal to `font_size`. Must be between 6 and 72. The default is 12. The font size in points. Must be between 6 and 12. The default is 12. ### checkbox place A location where the recipient, identified by `recipient_key`, checks or unchecks a box. Use `capture_as` to store the checkbox value in the envelope's captures. Specifies the type of place. For a checkbox place, the value must be `checkbox`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. A key that stores the recipient's input in the envelope's `captures` object. When set, the value entered or selected by the recipient is saved under this key after the envelope is completed. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. Set to `null` to disable capture. The symbol to display in the checkbox when it is checked. Available options are `check` and `xmark`. The default is `check`. Specifies whether the recipient must check this box to complete the signing ceremony. Possible values are `required` or `optional`. The default is `optional`. The height of the checkbox in points. The width equals the height. Must be between 8 and 40. Defaults to 20. ### dropdown place A location where the recipient, identified by `recipient_key`, selects from a list of options. Options can be a custom list of label-value pairs or a predefined set such as country names or US state codes. Use `capture_as` to store the selected value in the envelope's captures. Specifies the type of place. For a dropdown place, the value must be `dropdown`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. Specifies the list of options available in the dropdown. You can provide either **custom options** or a **predefined option set**. **Custom options**: An array of objects, each with a `label` (displayed to the user) and an optional `value` (captured when selected). If `value` is omitted, the `label` is used as the value. ```json "options": [ { "label": "Option A", "value": "a" }, { "label": "Option B", "value": "b" } ] ``` **Predefined options**: A string specifying a built-in option set: ValueDescription world_countries_namesCountry names (e.g., "United States", "Canada") world_countries_2_letter_codesISO 3166-1 alpha-2 codes (e.g., "US", "CA") world_countries_3_letter_codesISO 3166-1 alpha-3 codes (e.g., "USA", "CAN") world_countries_numeric_codesISO 3166-1 numeric codes (e.g., "840", "124") us_states_namesUS state names (e.g., "California", "Texas") us_states_2_letter_codesUS state codes (e.g., "CA", "TX") Specifies the option that is pre-selected when the dropdown is displayed. The value is first matched against the `label` of each option. If no match is found, it is matched against the `value` of each option. If no match is found, a validation error is returned. Specifies the behavior of the dropdown during the signing ceremony. Possible values: - `auto` (default): Automatically selects the best behavior based on the number of options. Uses `select` for 10 or fewer options, and `combobox` for more than 10 options. - `select`: Displays a standard dropdown list. Best for short lists where users can quickly scan all options. - `combobox`: Displays a searchable dropdown with type-ahead filtering. Best for long lists where users need to search for their selection. Specifies whether the recipient must select an option to complete the signing ceremony. Possible values are `required` or `optional`. The default is `required`. A placeholder message shown inside the dropdown field during the signing ceremony. Maximum length is 100 characters. Learn more in Hints and Prompts (/docs/api/resources/places/dropdown#hints-and-prompts). A tooltip message displayed when the user hovers over or focuses on the dropdown field during the signing ceremony. Maximum length is 100 characters. Learn more in Hints and Prompts (/docs/api/resources/places/dropdown#hints-and-prompts). A key that stores the recipient's input in the envelope's `captures` object. When set, the value entered or selected by the recipient is saved under this key after the envelope is completed. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. Set to `null` to disable capture. The font size in points. Must be between 6 and 12. The default is 12. The width of the dropdown field in points. Must be between 30 and 540. The default is 30. ### recipient completed date place Displays the date and time when the recipient, identified by `recipient_key`, completed their action on the envelope. Use `date_format` to control how the date is formatted. Specifies the type of place. For this kind of place, the value must be `recipient_completed_date`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. The date and time format using Moment.js syntax (https://momentjs.com/docs/#/displaying/format/). Common formats include `D MMM YYYY` (31 Dec 2025), `YYYY-MM-DD` (2025-12-31), and `MM/DD/YYYY` (12/31/2025). Defaults to `D MMM YYYY`. The font size in points. Must be between 1 and 144. Defaults to 12. ### envelope completed date place Displays the date and time when the envelope was completed. The envelope completes when all recipients have finished their actions. Use `date_format` to control how the date is formatted. Specifies the type of place. For this kind of place, the value must be `envelope_completed_date`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The date and time format using Moment.js syntax (https://momentjs.com/docs/#/displaying/format/). Common formats include `D MMM YYYY` (31 Dec 2025), `YYYY-MM-DD` (2025-12-31), and `MM/DD/YYYY` (12/31/2025). Defaults to `D MMM YYYY`. The font size in points. Must be between 1 and 144. Defaults to 12. ### recipient name place Displays the name of the recipient, identified by `recipient_key`, at a specific location on the document. The value is inserted automatically. This place is read-only and does not require any action from the recipient. Specifies the type of place. For this kind of place, the value must be `recipient_name`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. The font size in points. Must be between 1 and 144. Defaults to 12. ### recipient email place Displays the email address of the recipient, identified by `recipient_key`, at a specific location on the document. The value is inserted automatically. This place is read-only and does not require any action from the recipient. Specifies the type of place. For this kind of place, the value must be `recipient_email`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. The font size in points. Must be between 1 and 144. Defaults to 12. #### `recipients` (array of recipients, required) The recipients who participate in the envelope's signing process. An envelope can have between 1 and 10 recipients. Four types are supported: - `signer`: Signs the documents. - `preparer`: Fills in fields before signers receive the documents. - `approver`: Reviews and approves the documents without signing. - `automatic_signer`: Has their signature applied automatically. ### Signer The type of the recipient. Determines what actions the recipient can perform during the ceremony. TypeDescription signerSigns documents. Every envelope must have at least one signing recipient. approverReviews and approves documents without signing. preparerFills in document fields on behalf of another party. automatic_signerThe signature is applied automatically by the system. For signers, the type must be `signer`. A unique identifier you assign to each recipient in the envelope. Use it to match recipients with the places they should interact with (such as signature fields) and to identify them in events and webhook notifications. The key must start with a lowercase letter. It can contain lowercase letters, numbers, and underscores. Maximum 32 characters. It must be unique within the envelope. The full name of the recipient. Appears in invitation emails and is pre-filled for typed signatures. The email address of the recipient. SignatureAPI emails the ceremony link to this address when the ceremony uses `email_link` authentication, and the completed deliverable when `delivery_type` is `email`. Configuration for the first ceremony to create for the recipient. If not provided, a ceremony with `email_link` authentication is created by default. ### Ceremony ### Email Link Authentication With **email link authentication**, the recipient receives an email with a direct link to the ceremony. Clicking the link authenticates the recipient and opens the signing session. The type of authentication. Available values: `email_link`, `email_code`, and `custom`. For email link authentication, set `type` to `email_link`. A custom subject line for the invitation email sent to this recipient. When not set, the subject defaults to the envelope title (/docs/api/resources/envelopes/object#param-title). Maximum 500 characters. A custom message body for the invitation email sent to this recipient. When not set, the message defaults to the envelope message (/docs/api/resources/envelopes/object#param-message). Supports Markdown formatting: `**bold**`, `*italic*`, and `\n\n` for paragraph breaks. Maximum 2000 characters. ### Email Code Authentication With **email code authentication**, the recipient receives an email from SignatureAPI containing a 9-digit code. The recipient must enter this code to authenticate and access the ceremony. The type of authentication. Available values: `email_link`, `email_code`, and `custom`. For email code authentication, set `type` to `email_code`. ### Custom Authentication With **custom authentication**, your application authenticates the recipient. SignatureAPI provides a ceremony URL that you share or embed in your application to give the recipient access. The type of authentication. Available values: `email_link`, `email_code`, and `custom`. For custom authentication, set `type` to `custom`. The name of your company or application that authenticated the recipient. This value appears in the envelope audit log as the authentication provider. Key-value pairs with metadata about the authentication event, such as timestamps, session IDs, and user identifiers. These values appear in the envelope audit log. The values in `data` must be sufficient to verify how the recipient was authenticated. You must retain all records needed to prove the recipient's authentication, such as session information. In cases such as legal proceedings, you may need to provide these records to confirm identity. Review our Terms & Conditions (/docs/legal/terms/terms) for details. An HTTPS URL to redirect the recipient to after the ceremony finishes. Learn more in Redirect URL (/docs/api/resources/ceremonies/redirect-url). The delay in seconds before the ceremony redirects to `redirect_url` (standalone ceremonies) or emits completion events (embedded ceremonies). Defaults to `3`. Allowed range: `0` to `20`. Learn more in Redirect URL (/docs/api/resources/ceremonies/redirect-url). The format of the ceremony URL. Available options: - `standard` (default): Full-length URL. Works for most use cases. - `short`: Shortened URL. Use this when sharing through space-constrained channels such as SMS or push notifications. Origins allowed to embed this ceremony in an iframe. These values set the `frame-ancestors` directive in the ceremony's Content Security Policy (CSP) header. Sources typically take the form of a scheme and host (for example, `https://app.example.com`). Wildcards are supported (for example, `https://*.example.com`). For all available options, see the frame-ancestors documentation (https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/frame-ancestors#sources). Defaults to an empty list (`[]`), which means embedding is not allowed. To allow embedding from all origins (not recommended for production), use `["*"]`. Only the origin (scheme and host) is used. Paths are ignored. Controls whether the completed deliverable is automatically emailed to this recipient. ValueDescription emailThe completed deliverable is delivered to this recipient by email. This is the default for signers. noneThe completed deliverable is not emailed. Your application is responsible for distributing the deliverable. The signature methods available to the signer. The first item in the array is shown as the default. OptionDescription typedThe signer types their name. It is pre-filled from the recipient's name property. drawnThe signer draws their signature using a mouse, stylus, or touchscreen. If not specified, both `typed` and `drawn` are available, with `typed` shown first. ### Deprecated Fields How the ceremony is created for the recipient. Available options are `automatic` and `manual`. The default is `automatic`. This property is deprecated. Use the `ceremony` object on the recipient when creating an envelope to control ceremony creation. This property will continue to be supported for backwards compatibility. ### Preparer The type of the recipient. Determines what actions the recipient can perform during the ceremony. TypeDescription signerSigns documents. Every envelope must have at least one signing recipient. approverReviews and approves documents without signing. preparerFills in document fields on behalf of another party. automatic_signerThe signature is applied automatically by the system. For preparers, the type must be `preparer`. A unique identifier you assign to each recipient in the envelope. Use it to match recipients with the places they should interact with (such as signature fields) and to identify them in events and webhook notifications. The key must start with a lowercase letter. It can contain lowercase letters, numbers, and underscores. Maximum 32 characters. It must be unique within the envelope. The full name of the recipient. Appears in invitation emails. The email address of the recipient. SignatureAPI emails the ceremony link to this address when the ceremony uses `email_link` authentication, and the completed deliverable when `delivery_type` is `email`. Configuration for the first ceremony to create for the recipient. If not provided, a ceremony with `email_link` authentication is created by default. ### Ceremony ### Email Link Authentication With **email link authentication**, the recipient receives an email with a direct link to the ceremony. Clicking the link authenticates the recipient and opens the signing session. The type of authentication. Available values: `email_link`, `email_code`, and `custom`. For email link authentication, set `type` to `email_link`. A custom subject line for the invitation email sent to this recipient. When not set, the subject defaults to the envelope title (/docs/api/resources/envelopes/object#param-title). Maximum 500 characters. A custom message body for the invitation email sent to this recipient. When not set, the message defaults to the envelope message (/docs/api/resources/envelopes/object#param-message). Supports Markdown formatting: `**bold**`, `*italic*`, and `\n\n` for paragraph breaks. Maximum 2000 characters. ### Email Code Authentication With **email code authentication**, the recipient receives an email from SignatureAPI containing a 9-digit code. The recipient must enter this code to authenticate and access the ceremony. The type of authentication. Available values: `email_link`, `email_code`, and `custom`. For email code authentication, set `type` to `email_code`. ### Custom Authentication With **custom authentication**, your application authenticates the recipient. SignatureAPI provides a ceremony URL that you share or embed in your application to give the recipient access. The type of authentication. Available values: `email_link`, `email_code`, and `custom`. For custom authentication, set `type` to `custom`. The name of your company or application that authenticated the recipient. This value appears in the envelope audit log as the authentication provider. Key-value pairs with metadata about the authentication event, such as timestamps, session IDs, and user identifiers. These values appear in the envelope audit log. The values in `data` must be sufficient to verify how the recipient was authenticated. You must retain all records needed to prove the recipient's authentication, such as session information. In cases such as legal proceedings, you may need to provide these records to confirm identity. Review our Terms & Conditions (/docs/legal/terms/terms) for details. An HTTPS URL to redirect the recipient to after the ceremony finishes. Learn more in Redirect URL (/docs/api/resources/ceremonies/redirect-url). The delay in seconds before the ceremony redirects to `redirect_url` (standalone ceremonies) or emits completion events (embedded ceremonies). Defaults to `3`. Allowed range: `0` to `20`. Learn more in Redirect URL (/docs/api/resources/ceremonies/redirect-url). The format of the ceremony URL. Available options: - `standard` (default): Full-length URL. Works for most use cases. - `short`: Shortened URL. Use this when sharing through space-constrained channels such as SMS or push notifications. Origins allowed to embed this ceremony in an iframe. These values set the `frame-ancestors` directive in the ceremony's Content Security Policy (CSP) header. Sources typically take the form of a scheme and host (for example, `https://app.example.com`). Wildcards are supported (for example, `https://*.example.com`). For all available options, see the frame-ancestors documentation (https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/frame-ancestors#sources). Defaults to an empty list (`[]`), which means embedding is not allowed. To allow embedding from all origins (not recommended for production), use `["*"]`. Only the origin (scheme and host) is used. Paths are ignored. Controls whether SignatureAPI emails the completed deliverable to the recipient once the envelope is finished. ValueDescription emailThe completed deliverable is delivered to this recipient by email. noneNo emails are sent. Your application is responsible for distributing the ceremony URL and the completed deliverable. This is the default for preparers. ### Deprecated Fields How the ceremony is created for the recipient. Available options are `automatic` and `manual`. The default is `automatic`. This property is deprecated. Use the `ceremony` object on the recipient when creating an envelope to control ceremony creation. This property will continue to be supported for backwards compatibility. ### Approver The type of the recipient. Determines what actions the recipient can perform during the ceremony. TypeDescription signerSigns documents. Every envelope must have at least one signing recipient. approverReviews and approves documents without signing. preparerFills in document fields on behalf of another party. automatic_signerThe signature is applied automatically by the system. For approvers, the type must be `approver`. A unique identifier you assign to each recipient in the envelope. Use it to match recipients with the places they should interact with (such as signature fields) and to identify them in events and webhook notifications. The key must start with a lowercase letter. It can contain lowercase letters, numbers, and underscores. Maximum 32 characters. It must be unique within the envelope. The full name of the recipient. Appears in invitation emails. The email address of the recipient. SignatureAPI emails the ceremony link to this address when the ceremony uses `email_link` authentication, and the completed deliverable when `delivery_type` is `email`. Configuration for the first ceremony to create for the recipient. If not provided, a ceremony with `email_link` authentication is created by default. ### Ceremony ### Email Link Authentication With **email link authentication**, the recipient receives an email with a direct link to the ceremony. Clicking the link authenticates the recipient and opens the signing session. The type of authentication. Available values: `email_link`, `email_code`, and `custom`. For email link authentication, set `type` to `email_link`. A custom subject line for the invitation email sent to this recipient. When not set, the subject defaults to the envelope title (/docs/api/resources/envelopes/object#param-title). Maximum 500 characters. A custom message body for the invitation email sent to this recipient. When not set, the message defaults to the envelope message (/docs/api/resources/envelopes/object#param-message). Supports Markdown formatting: `**bold**`, `*italic*`, and `\n\n` for paragraph breaks. Maximum 2000 characters. ### Email Code Authentication With **email code authentication**, the recipient receives an email from SignatureAPI containing a 9-digit code. The recipient must enter this code to authenticate and access the ceremony. The type of authentication. Available values: `email_link`, `email_code`, and `custom`. For email code authentication, set `type` to `email_code`. ### Custom Authentication With **custom authentication**, your application authenticates the recipient. SignatureAPI provides a ceremony URL that you share or embed in your application to give the recipient access. The type of authentication. Available values: `email_link`, `email_code`, and `custom`. For custom authentication, set `type` to `custom`. The name of your company or application that authenticated the recipient. This value appears in the envelope audit log as the authentication provider. Key-value pairs with metadata about the authentication event, such as timestamps, session IDs, and user identifiers. These values appear in the envelope audit log. The values in `data` must be sufficient to verify how the recipient was authenticated. You must retain all records needed to prove the recipient's authentication, such as session information. In cases such as legal proceedings, you may need to provide these records to confirm identity. Review our Terms & Conditions (/docs/legal/terms/terms) for details. An HTTPS URL to redirect the recipient to after the ceremony finishes. Learn more in Redirect URL (/docs/api/resources/ceremonies/redirect-url). The delay in seconds before the ceremony redirects to `redirect_url` (standalone ceremonies) or emits completion events (embedded ceremonies). Defaults to `3`. Allowed range: `0` to `20`. Learn more in Redirect URL (/docs/api/resources/ceremonies/redirect-url). The format of the ceremony URL. Available options: - `standard` (default): Full-length URL. Works for most use cases. - `short`: Shortened URL. Use this when sharing through space-constrained channels such as SMS or push notifications. Origins allowed to embed this ceremony in an iframe. These values set the `frame-ancestors` directive in the ceremony's Content Security Policy (CSP) header. Sources typically take the form of a scheme and host (for example, `https://app.example.com`). Wildcards are supported (for example, `https://*.example.com`). For all available options, see the frame-ancestors documentation (https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/frame-ancestors#sources). Defaults to an empty list (`[]`), which means embedding is not allowed. To allow embedding from all origins (not recommended for production), use `["*"]`. Only the origin (scheme and host) is used. Paths are ignored. Controls whether SignatureAPI emails the completed deliverable to the recipient once the envelope is finished. ValueDescription emailThe completed deliverable is delivered to this recipient by email. noneNo emails are sent. Your application is responsible for distributing the ceremony URL and the completed deliverable. This is the default for approvers. ### Deprecated Fields How the ceremony is created for the recipient. Available options are `automatic` and `manual`. The default is `automatic`. This property is deprecated. Use the `ceremony` object on the recipient when creating an envelope to control ceremony creation. This property will continue to be supported for backwards compatibility. ### Automatic Signer The type of the recipient. Determines what actions the recipient can perform during the ceremony. TypeDescription signerSigns documents. Every envelope must have at least one signing recipient. approverReviews and approves documents without signing. preparerFills in document fields on behalf of another party. automatic_signerThe signature is applied automatically by the system. For automatic signers, the type must be `automatic_signer`. A unique identifier you assign to each recipient in the envelope. Use it to match recipients with the places they should interact with (such as signature fields) and to identify them in events and webhook notifications. The key must start with a lowercase letter. It can contain lowercase letters, numbers, and underscores. Maximum 32 characters. It must be unique within the envelope. The full name of the signer. Appears in the audit log line that records the automatic signature. A short statement explaining why the initiator is authorized to sign on behalf of this person. This string is shown as-is in the audit log. Maximum 500 characters. Cannot be empty. The signature image to apply to the document. Required when the recipient is assigned any place of type `signature`. ### Preset symbol The symbol type. Currently only `drawn` is supported. The URL of a PNG upload owned by your account. Both temporary uploads (from `POST /v1/uploads`) and permanent uploads stored via the Dashboard or `POST /v1/uploads/{id}/store` are accepted. The upload must not be expired. The initials image to apply to the document. Required when the recipient is assigned any place of type `initials`. Same shape as `signature`. Automatic signers do not accept `email`, `ceremony`, `delivery_type`, or `signature_options`. They do not receive invitations or access a ceremony. ### Signing options #### `routing` (enum) Controls the order in which recipients receive and act on the envelope. - `sequential`: Recipients act one at a time, in the order listed. Each recipient must complete before the next is notified. This is the default. - `parallel`: All recipients are notified at the same time and can act in any order. Learn more about recipient routing (/docs/api/resources/envelopes/routing). #### `deliverable` (deliverable object) Configuration for the deliverable generated when the envelope is completed. The deliverable is sent to all recipients via email. To prevent automatic delivery to a recipient, set that recipient's `delivery_type` to `none`. If omitted, a `standard` deliverable is generated automatically. ### Standard Deliverable The standard deliverable includes an audit log. To get signed documents without an audit log, use the simple deliverable (/docs/api/resources/deliverables/simple) instead. A user-provided name for this deliverable. Use this to identify deliverables when an envelope has more than one. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Between 1 and 32 characters. The type of the deliverable. - `standard`: Includes the signed documents and an audit log with a certificate of completion. This is the default. - `simple`: Includes the signed documents only, without an audit log. For standard deliverables, the type is `standard`. The language for system-generated text in the audit log, including labels and the certificate of completion. Does not affect the content of the signed documents. Supported values: `en` (English), `es` (Spanish), `fr` (French), `it` (Italian), `pt` (Portuguese), `de` (German), `zh` (Chinese Simplified), `hu` (Hungarian). Defaults to the envelope language. The timezone used for timestamps in the audit log. Must be a valid IANA Time Zone Database identifier (e.g., `America/New_York`, `Europe/London`). Does not affect timestamps inside the signed documents. Defaults to the envelope timezone. The format for timestamps in the audit log. Uses MomentJS format tokens (e.g., `MM/DD/YYYY HH:mm:ss`). Does not affect timestamps inside the signed documents. Defaults to the envelope timestamp format. The keys of the documents to include in the deliverable. By default, all documents in the envelope are included. Use this to create a deliverable with only a subset of documents. For example, generate separate deliverables for different recipients. Accepts between 1 and 10 document keys. The password used to encrypt the deliverable. Recipients must enter this password to access the downloaded file. Password requirements: - Between 4 and 32 characters - Letters and numbers only (no special characters or spaces) When returned in API responses, the password value is masked for security (displayed as `********`). Password protection is available upon request. Contact support (/support) to enable this feature. ### Simple Deliverable The simple deliverable does not include an audit log. To get signed documents with an audit log, use the standard deliverable (/docs/api/resources/deliverables/standard) instead. A user-provided name for this deliverable. Use this to identify deliverables when an envelope has more than one. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Between 1 and 32 characters. The type of the deliverable. - `standard`: Includes the signed documents and an audit log with a certificate of completion. This is the default. - `simple`: Includes the signed documents only, without an audit log. For simple deliverables, the type is `simple`. The keys of the documents to include in the deliverable. By default, all documents in the envelope are included. Use this to create a deliverable with only a subset of documents. For example, generate separate deliverables for different recipients. Accepts between 1 and 10 document keys. The password used to encrypt the deliverable. Recipients must enter this password to access the downloaded file. Password requirements: - Between 4 and 32 characters - Letters and numbers only (no special characters or spaces) When returned in API responses, the password value is masked for security (displayed as `********`). Password protection is available upon request. Contact support (/support) to enable this feature. #### `attestation` (enum) The regulatory attestation applied to the envelope. Use this to meet country-specific e-signature requirements. - `none`: No attestation. This is the default and covers most countries, including the US and EU member states. - `mx_nom151`: Mexico NOM-151 compliance. Attaches a preservation certificate to the deliverable. - `br_icp_brasil`: Brazil ICP-Brasil trusted timestamp. Embeds a timestamp in the deliverable. For more information, see Attestation (/docs/api/resources/envelopes/attestation). ### Recipient experience #### `message` (string) A custom message included in the signing request emails sent to recipients. Use it to provide context about what is being signed. Supports up to 2,000 characters. Accepts a subset of Markdown: - `**bold**` for bold text - `*italic*` for italic text - `\n\n` for paragraph breaks Defaults to `null`. #### `language` (string) The language used for the signing ceremony, recipient emails, and the audit log in deliverables. Supported values: `en` (English), `es` (Spanish), `fr` (French), `it` (Italian), `pt` (Portuguese), `de` (German), `zh` (Chinese Simplified), `hu` (Hungarian). If not specified, the account's default language is used. Learn more about language (/docs/api/resources/envelopes/language). #### `timezone` (string) The time zone applied to timestamps in the deliverable's audit log. Must be a valid IANA Time Zone Database identifier (for example, `America/New_York` or `Europe/London`). If not specified, the account's default time zone is used. Learn more about time zones (/docs/api/resources/envelopes/timezone). #### `timestamp_format` (string) The date and time format used for timestamps in the deliverable's audit log. Uses MomentJS format tokens (for example, `MM/DD/YYYY HH:mm:ss`). If not specified, the account's default timestamp format is used. Learn more about timestamp formats (/docs/api/resources/envelopes/timestamp-format). #### `sender` (object) The sender of the envelope. Sender information appears in emails sent to recipients, identifying who initiated the signing request. If omitted, the account's default sender name and email are used. ### Sender The name of the sender, displayed to recipients in emails and the signing ceremony. Maximum 500 characters. The email address of the sender, shown to recipients for reference. Maximum 320 characters. The organization name of the sender, displayed to recipients alongside the sender's name and email. Defaults to `null`. Maximum 500 characters. #### `branding` (object) Customizes the visual appearance of the signing ceremony and recipient emails. Branding does not affect internal notifications or signed documents. Learn more about branding (/docs/api/resources/envelopes/branding). ### Branding The URL of the logo image displayed in the header of emails and the signing ceremony. Must be a PNG file uploaded to the Library. Defaults to `null`. Only files uploaded to your account's Library are accepted. Direct external URLs are not supported. The accent color applied to buttons in emails and the signing ceremony. Specified as a hex color code (for example, `#2463eb`). Defaults to `#2463eb`. The color must have a contrast ratio of at least 4.5:1 against white, following WCAG guidelines (https://www.w3.org/TR/WCAG21/). If the color does not meet this requirement, the API returns an error with a suggested compliant alternative. Additional customization for emails sent to recipients, including footer text and logo alignment. ### Email options A custom footer included at the bottom of all recipient emails for this envelope, after SignatureAPI's standard footer content. Use it for disclaimers, privacy notices, or contact information. Defaults to `null`. Supports a subset of Markdown: `**bold**`, `*italic*`, and `\n\n` for paragraph breaks. Maximum 10,000 characters. The horizontal alignment of the logo in recipient emails. Accepted values are `left`, `center`, and `right`. Defaults to `left`. ### Organization #### `label` (string) A custom label for internal identification. Labels are not shown to recipients. Unlike `title`, which recipients see, the label is for your team's use only. It can be updated at any time via the Update Envelope endpoint. Maximum 500 characters. Defaults to `null`. #### `topics` (array of strings) An array of up to 10 tags used to classify the envelope and filter webhook notifications. Each topic must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters per topic. Learn more about topics (/docs/api/resources/envelopes/topics). #### `metadata` (object) A set of up to 10 custom key-value pairs for attaching internal reference data to the envelope. Use metadata to link envelopes to records in your own systems. Keys: up to 32 characters (letters, digits, and underscores). Values: up to 1,000 characters. Do not store sensitive information as metadata. Learn more about metadata (/docs/api/resources/envelopes/metadata). ## Returns Returns a `201 Created` status code along with an envelope object (/docs/api/resources/envelopes/object) on success, or an error (/docs/api/errors) otherwise. ```json Request (minimal) // POST https://api.signatureapi.com/v1/envelopes // X-API-Key: key_test_... // Content-Type: application/json { "title": "Service Agreement", "message": "Please review the privacy policy and provide your signature.", "documents": [ { "url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/privacy-placeholder.pdf", "format": "pdf", "places": [ { "key": "signer_signs_here", "type": "signature", "recipient_key": "visitor" } ] } ], "recipients": [ { "type": "signer", "key": "visitor", "name": "John Doe", "email": "john@example.com" } ] } ``` ```json Request (full) // POST https://api.signatureapi.com/v1/envelopes // X-API-Key: key_test_... // Content-Type: application/json { "title": "Exploration Agreement", "label": "Exploration Agreement for Order Ref. 25005", "routing": "sequential", "message": "Please review the agreement and provide your signature.", "topics": [ "sales", "project_blue" ], "metadata": { "customer_ref": "x9550501", "account_annual_revenue": "$4,500,000" }, "branding": { "logo": "https://api.signatureapi.com/v1/uploads/upl_3jBYlxa9gv0fGLzFAnfwxe", "accent_color": "#9810fa", "email": { "footer": "**Disclaimer:** This email and its attachments may contain confidential information. If you are not the intended recipient, please delete it and notify the sender.", "logo_position": "left" } }, "documents": [ { "title": "Exploration Agreement", "url": "https://pub-e5051420e98a4fdfb3fd42a62fbf06fa.r2.dev/dummy.docx", "format": "docx", "data": { "date": "December 31st, 2025", "showAlert": true, "serviceProvider": { "name": "Jane Smith", "organization": "ACME Global, Inc." }, "client": { "name": "Michael J. Miller", "organization": "Miller Industries" } }, "places": [ { "key": "provider_signs_here", "type": "signature", "recipient_key": "service_provider", "height": 60 }, { "key": "client_signs_here", "type": "signature", "recipient_key": "client", "height": 60 } ] } ], "recipients": [ { "type": "signer", "key": "service_provider", "name": "Jane Smith", "email": "jane@example.com", "signature_options": ["typed", "drawn"], "delivery_type": "email", "ceremony": { "authentication": [ { "type": "email_code" } ], "redirect_url": "https://example.com/after-signing", "embeddable_in": [], "url_variant": "short" } }, { "type": "signer", "key": "client", "name": "Michael J. Miller", "email": "michael@example.com", "signature_options": ["drawn"], "delivery_type": "email", "ceremony": { "authentication": [ { "type": "custom", "provider": "My App", "data": { "session_id": "1234567890", "user_id": "user123" } } ], "redirect_url": null, "embeddable_in": [], "url_variant": "standard" } } ], "deliverable": { "type": "standard", "language": "en", "timezone": "UTC", "timestamp_format": "MM/DD/YYYY HH:mm:ss" } } ``` ```json // HTTP/1.1 201 Created { "id": "55072f0e-b919-4d69-89cd-e7e56af00530", "title": "Exploration Agreement", "label": "Exploration Agreement for Order Ref. 25005", "message": "Please review the agreement and provide your signature.", "topics": [ "sales", "project_blue" ], "metadata": { "customer_ref": "x9550501", "account_annual_revenue": "$4,500,000" }, "status": "processing", "mode": "live", "routing": "sequential", "language": "en", "timezone": "UTC", "timestamp_format": "MM/DD/YYYY HH:mm:ss", "attestation": "none", "branding": { "logo": "https://api.signatureapi.com/v1/uploads/upl_3jBYlxa9gv0fGLzFAnfwxe", "accent_color": "#9810fa", "email": { "from": "noreply@signatureapi.com", "footer": "**Disclaimer:** This email and its attachments may contain confidential information. If you are not the intended recipient, please delete it and notify the sender.", "logo_position": "left" } }, "sender": { "name": "Jennifer Lee", "email": "jennifer@example.com", "organization": "Acme Enterprises" }, "documents": [ { "id": "doc_3jBYlxa9gv0fGLzFAnfwxe", "envelope_id": "55072f0e-b919-4d69-89cd-e7e56af00530", "title": "Exploration Agreement", "page_count": 2, "url": "https://pub-e5051420e98a4fdfb3fd42a62fbf06fa.r2.dev/dummy.docx", "format": "docx", "data": { "date": "December 31st, 2025", "showAlert": true, "serviceProvider": { "name": "Jane Smith", "organization": "ACME Global, Inc." }, "client": { "name": "Michael J. Miller", "organization": "Miller Industries" } }, "places": [ { "key": "provider_signs_here", "type": "signature", "recipient_key": "service_provider", "height": 60 }, { "key": "client_signs_here", "type": "signature", "recipient_key": "client", "height": 60 } ] } ], "recipients": [ { "id": "re_26w2VVV5JVm4j459TY5BNM", "envelope_id": "55072f0e-b919-4d69-89cd-e7e56af00530", "type": "signer", "key": "service_provider", "name": "Jane Smith", "email": "jane@example.com", "status": "pending", "ceremony": { "authentication": [ { "type": "email_link", "subject_override": null, "message_override": null } ], "redirect_url": null, "redirect_delay": 3, "embeddable_in": [], "url_variant": "standard", "url": null }, "delivery_type": "email", "ceremony_creation": "automatic", "signature_options": ["typed", "drawn"], "completed_at": null, "status_updated_at": "2025-12-31T12:00:01.000Z" }, { "id": "re_38UVwrWdCqX5kqeKFJUTtf", "envelope_id": "55072f0e-b919-4d69-89cd-e7e56af00530", "type": "signer", "key": "client", "name": "Michael J. Miller", "email": "michael@example.com", "status": "pending", "ceremony": { "authentication": [ { "type": "email_link", "subject_override": null, "message_override": null } ], "redirect_url": null, "redirect_delay": 3, "embeddable_in": [], "url_variant": "standard", "url": null }, "delivery_type": "email", "ceremony_creation": "automatic", "signature_options": ["drawn"], "completed_at": null, "status_updated_at": "2025-12-31T12:00:01.000Z" } ], "deliverable": { "id": "del_1T7If8GgrTOf7zBVPaJf2e", "name": null, "envelope_id": "55072f0e-b919-4d69-89cd-e7e56af00530", "type": "standard", "status": "pending", "url": null, "language": "en", "timezone": "UTC", "timestamp_format": "MM/DD/YYYY HH:mm:ss", "included_documents": null, "password": null, "created_at": "2025-12-31T12:00:00.000Z", "generated_at": null }, "captures": {}, "snapshot_url": null, "created_at": "2025-12-31T12:00:00.000Z", "completed_at": null } ``` ## List envelopes URL: https://signatureapi.com/docs/api/resources/envelopes/list Description: Returns a paginated list of all envelopes in your account Returns a paginated list of envelopes in the current account, sorted by creation date with the most recent envelopes first. Use the `status` parameter to filter by envelope status and the `topic` parameter to filter by topic tag. ## Query parameters Filter the list to envelopes with this status. Accepted values: `processing`, `in_progress`, `completed`, `failed`, and `canceled`. Filter the list to envelopes with this topic (/docs/api/resources/envelopes/topics) tag. The maximum number of objects to return in the response, up to 20. The default is 20. For certain use cases we can increase the limit. Please contact support (mailto:support@signatureapi.com). ## Returns Returns a `200 OK` status code along with a paginated (/docs/api/pagination) list of envelope objects (/docs/api/resources/envelopes/object) on success, or an error (/docs/api/errors) otherwise. ```json // GET https://api.signatureapi.com/v1/envelopes // X-API-Key: key_test_... ``` ```json // HTTP/1.1 200 OK { "links": { "next": "https://api.signatureapi.com/v1/envelopes?cursor=seq_0thJdKRhN4&limit=20", "previous": null }, "data": [ { "id": "55072f0e-b919-4d69-89cd-e7e56af00530", "title": "Exploration Agreement", //... }, { "id": "a4ef2b1c-d834-4a72-bc19-e7e56af00531", "title": "Service Contract", //... }, { "id": "b8c3f901-e219-4b63-ad27-e7e56af00532", "title": "Non-Disclosure Agreement", //... } ] } ``` ## Retrieve an envelope URL: https://signatureapi.com/docs/api/resources/envelopes/get Description: Retrieve the full details of an existing envelope Retrieves the full details of an envelope, including its documents, recipients, deliverable, sender information, and captures. Use this endpoint to check the current status of an envelope, retrieve recipient ceremony URLs, or access the deliverable download URL after completion. All properties are returned regardless of the envelope's current status. Properties not yet available (such as `completed_at` for an in-progress envelope) are returned as `null`. ## Path parameters The unique identifier of the envelope, in UUID format. ## Returns Returns a `200 OK` status code along with an envelope object (/docs/api/resources/envelopes/object) on success, or an error (/docs/api/errors) otherwise. ```json // GET https://api.signatureapi.com/v1/envelopes/{envelope_id} // X-API-Key: key_test_... ``` ```json // HTTP/1.1 200 OK { "id": "55072f0e-b919-4d69-89cd-e7e56af00530", "title": "Exploration Agreement", "label": "Exploration Agreement for Order Ref. 25005", "message": "Please review the agreement and provide your signature.", "status": "completed", "mode": "live", "routing": "sequential", "language": "en", "timezone": "America/New_York", "timestamp_format": "MM/DD/YYYY HH:mm:ss", "attestation": "none", "branding": { "logo": null, "accent_color": "#2463eb", "email": { "from": "noreply@signatureapi.com", "footer": null, "logo_position": "left" } }, "sender": { "name": "Jennifer Lee", "email": "jennifer@example.com", "organization": "Acme Enterprises" }, "topics": [ "sales", "project_blue" ], "metadata": { "customer_ref": "x9550501", "account_annual_revenue": "$4,500,000" }, "documents": [ { "id": "doc_3jBYlxa9gv0fGLzFAnfwxe", "envelope_id": "55072f0e-b919-4d69-89cd-e7e56af00530", "title": "Exploration Agreement", "page_count": 2, "url": "https://pub-e5051420e98a4fdfb3fd42a62fbf06fa.r2.dev/dummy.docx", "format": "docx", "data": { "date": "December 31st, 2025", "showAlert": true, "serviceProvider": { "name": "Jane Smith", "organization": "ACME Global, Inc." }, "client": { "name": "Michael J. Miller", "organization": "Miller Industries" } }, "places": [ { "key": "provider_signs_here", "type": "signature", "recipient_key": "service_provider" }, { "key": "client_signs_here", "type": "signature", "recipient_key": "client" } ] } ], "recipients": [ { "id": "re_26w2VVV5JVm4j459TY5BNM", "envelope_id": "55072f0e-b919-4d69-89cd-e7e56af00530", "type": "signer", "key": "service_provider", "name": "Jane Smith", "email": "jane@example.com", "status": "completed", "ceremony": { "authentication": [ { "type": "email_link", "subject_override": null, "message_override": null } ], "redirect_url": null, "redirect_delay": 3, "embeddable_in": [], "url_variant": "standard", "url": null }, "delivery_type": "email", "ceremony_creation": "automatic", "signature_options": ["typed", "drawn"], "completed_at": "2025-12-31T14:00:00.000Z", "status_updated_at": "2025-12-31T14:00:00.000Z" }, { "id": "re_38UVwrWdCqX5kqeKFJUTtf", "envelope_id": "55072f0e-b919-4d69-89cd-e7e56af00530", "type": "signer", "key": "client", "name": "Michael J. Miller", "email": "michael@example.com", "status": "completed", "ceremony": { "authentication": [ { "type": "email_link", "subject_override": null, "message_override": null } ], "redirect_url": null, "redirect_delay": 3, "embeddable_in": [], "url_variant": "standard", "url": null }, "delivery_type": "email", "ceremony_creation": "automatic", "signature_options": ["typed", "drawn"], "completed_at": "2025-12-31T15:00:00.000Z", "status_updated_at": "2025-12-31T15:00:00.000Z" } ], "deliverable": { "id": "del_1T7If8GgrTOf7zBVPaJf2e", "name": null, "envelope_id": "55072f0e-b919-4d69-89cd-e7e56af00530", "type": "standard", "status": "generated", "url": "https://s3.us-east-2.amazonaws.com/signatureapi-vault-dev/envelopes/55072f0e...", "language": "en", "timezone": "America/New_York", "timestamp_format": "MM/DD/YYYY HH:mm:ss", "included_documents": null, "password": null, "created_at": "2025-12-31T12:00:00.000Z", "generated_at": "2025-12-31T15:00:05.000Z" }, "captures": {}, "snapshot_url": null, "created_at": "2025-12-31T12:00:00.000Z", "completed_at": "2025-12-31T15:00:00.000Z" } ``` ## Update an envelope URL: https://signatureapi.com/docs/api/resources/envelopes/update Description: Update the label of an existing envelope Updates an envelope by setting the values of the properties passed. Any properties not provided are left unchanged. Currently, only the `label` property can be updated. The label is for internal use and is not shown to recipients. It can be updated regardless of the envelope's status. ## Path parameters The unique identifier of the envelope, in UUID format. ## Body parameters #### `label` (string) A custom label for internal identification. Labels are not shown to recipients. Unlike `title`, which recipients see, the label is for your team's use only. It can be updated at any time via the Update Envelope endpoint. Maximum 500 characters. Defaults to `null`. ## Returns Returns a `200 OK` status code along with the updated envelope object (/docs/api/resources/envelopes/object) on success, or an error (/docs/api/errors) otherwise. ```json // PATCH https://api.signatureapi.com/v1/envelopes/{envelope_id} // X-API-Key: key_test_... // Content-Type: application/json { "label": "Exploration Agreement for Order Ref. 29009" } ``` ```json // HTTP/1.1 200 OK { "id": "55072f0e-b919-4d69-89cd-e7e56af00530", "title": "Exploration Agreement", "label": "Exploration Agreement for Order Ref. 29009", //... } ``` ## Delete an envelope URL: https://signatureapi.com/docs/api/resources/envelopes/delete Description: Permanently delete a canceled, failed, or completed envelope Permanently deletes an envelope. The envelope immediately becomes inaccessible through the API. Only envelopes with status `canceled`, `completed`, or `failed` can be deleted. To delete an envelope in `processing` or `in_progress` status, cancel it first (/docs/api/resources/envelopes/cancel). Deleted envelopes can be recovered via a support request within 14 days. After 14 days, the data is permanently removed. ## Path parameters The unique identifier of the envelope, in UUID format. ## Returns Returns a `204 No Content` status code on success, or an error (/docs/api/errors) otherwise. ```json // DELETE https://api.signatureapi.com/v1/envelopes/{envelope_id} // X-API-Key: key_test_... ``` ## Cancel an envelope URL: https://signatureapi.com/docs/api/resources/envelopes/cancel Description: Cancel an in-progress envelope to permanently halt the signing process Cancels an envelope, immediately halting all signing activity. Once canceled, recipients can no longer access the signing ceremony. This action is irreversible and permanent. Only envelopes with status `in_progress` can be canceled. ## Path parameters The unique identifier of the envelope, in UUID format. ## Body parameters #### `reason` (string) An optional explanation for why the envelope was canceled. This is for internal use only and is not shown to recipients. The reason is included in the `envelope.canceled` webhook event payload. Maximum 2,000 characters. ## Returns Returns a `200 OK` status code along with an envelope object (/docs/api/resources/envelopes/object) on success, or an error (/docs/api/errors) otherwise. ```json // POST https://api.signatureapi.com/v1/envelopes/{envelope_id}/cancel // X-API-Key: key_test_... // Content-Type: application/json { "reason": "Price renegotiated by John D." } ``` ```json // HTTP/1.1 200 OK { "id": "55072f0e-b919-4d69-89cd-e7e56af00530", "title": "Exploration Agreement", "status": "canceled", //... } ``` ## Recipient URL: https://signatureapi.com/docs/api/resources/recipients/object Description: The recipient object represents a person who participates in an envelope as a signer, approver, preparer, or automatic signer A **recipient** is a person who receives and acts on an envelope. Every envelope must have at least one recipient. Recipients have four types, each with a different role: | Type | Description | |------|-------------| | Signer (/docs/api/resources/recipients/signer) | Reviews documents and adds a signature or initials. Every envelope must have at least one signing recipient. | | Approver (/docs/api/resources/recipients/approver) | Reviews and approves documents without signing. Approver actions are not recorded in the audit log. | | Preparer (/docs/api/resources/recipients/preparer) | Fills in document fields before signers receive the envelope. Preparer actions are not recorded in the audit log. | | Automatic Signer (/docs/api/resources/recipients/automatic-signer) | The signature is applied automatically by the system. No ceremony, no email. | Each recipient participates in the envelope through a **ceremony**, a guided session where they complete their assigned actions. Automatic signers are the exception: they do not access a ceremony; their signature is applied automatically by the system. A recipient's `status` tracks their progress through the workflow. See the recipient lifecycle (/docs/api/resources/recipients/lifecycle) for details on each status and what triggers a transition. A recipient belongs to an envelope (/docs/api/resources/envelopes/object). ## Attributes ### Signer The unique identifier of the recipient. Recipient IDs use the `re_` prefix. The unique identifier of the envelope, in UUID format. The type of the recipient. Determines what actions the recipient can perform during the ceremony. TypeDescription signerSigns documents. Every envelope must have at least one signing recipient. approverReviews and approves documents without signing. preparerFills in document fields on behalf of another party. automatic_signerThe signature is applied automatically by the system. For signers, the type is `signer`. A unique identifier you assign to each recipient in the envelope. Use it to match recipients with the places they should interact with (such as signature fields) and to identify them in events and webhook notifications. The key must start with a lowercase letter. It can contain lowercase letters, numbers, and underscores. Maximum 32 characters. It must be unique within the envelope. The full name of the recipient. Appears in invitation emails and is pre-filled for typed signatures. The email address of the recipient. SignatureAPI emails the ceremony link to this address when the ceremony uses `email_link` authentication, and the completed deliverable when `delivery_type` is `email`. The current status of the recipient in the signing workflow. StatusDescription pendingThe envelope has not been sent to the recipient yet. This is the initial status. awaitingThe recipient is waiting for earlier recipients in the routing order to complete. sentThe invitation has been sent to the recipient. completedThe recipient has completed their required actions (for example, signed or approved). rejectedThe recipient declined to complete the envelope. soft_bouncedThe invitation email was temporarily undeliverable (for example, a full mailbox). You can resend the request. hard_bouncedThe invitation email was permanently undeliverable (for example, an invalid address). Use the Replace endpoint to assign a new recipient. failedAn error occurred and the invitation could not be sent. replacedThis recipient was replaced with a new one via the Replace endpoint. The current ceremony (/docs/api/resources/ceremonies/object) for the recipient. ### Ceremony ### Email Link Authentication With **email link authentication**, the recipient receives an email with a direct link to the ceremony. Clicking the link authenticates the recipient and opens the signing session. The type of authentication. Available values: `email_link`, `email_code`, and `custom`. For email link authentication, this value is `email_link`. The custom subject line used for this recipient's invitation email. `null` if the envelope title is used. The custom message body used for this recipient's invitation email. `null` if the envelope message is used. ### Email Code Authentication With **email code authentication**, the recipient receives an email from SignatureAPI containing a 9-digit code. The recipient must enter this code to authenticate and access the ceremony. The type of authentication. Available values: `email_link`, `email_code`, and `custom`. For email code authentication, this value is `email_code`. ### Custom Authentication With **custom authentication**, your application authenticates the recipient. SignatureAPI provides a ceremony URL that you share or embed in your application to give the recipient access. The type of authentication. Available values: `email_link`, `email_code`, and `custom`. For custom authentication, this value is `custom`. The name of your company or application that authenticated the recipient. This value appears in the envelope audit log as the authentication provider. Key-value pairs with metadata about the authentication event, such as timestamps, session IDs, and user identifiers. These values appear in the envelope audit log. The values in `data` must be sufficient to verify how the recipient was authenticated. You must retain all records needed to prove the recipient's authentication, such as session information. In cases such as legal proceedings, you may need to provide these records to confirm identity. Review our Terms & Conditions (/docs/legal/terms/terms) for details. An HTTPS URL to redirect the recipient to after the ceremony finishes. Learn more in Redirect URL (/docs/api/resources/ceremonies/redirect-url). The delay in seconds before the ceremony redirects to `redirect_url` (standalone ceremonies) or emits completion events (embedded ceremonies). Defaults to `3`. Allowed range: `0` to `20`. Learn more in Redirect URL (/docs/api/resources/ceremonies/redirect-url). The format of the ceremony URL. Available options: - `standard` (default): Full-length URL. Works for most use cases. - `short`: Shortened URL. Use this when sharing through space-constrained channels such as SMS or push notifications. Origins allowed to embed this ceremony in an iframe. These values set the `frame-ancestors` directive in the ceremony's Content Security Policy (CSP) header. Sources typically take the form of a scheme and host (for example, `https://app.example.com`). Wildcards are supported (for example, `https://*.example.com`). For all available options, see the frame-ancestors documentation (https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/frame-ancestors#sources). Defaults to an empty list (`[]`), which means embedding is not allowed. To allow embedding from all origins (not recommended for production), use `["*"]`. Only the origin (scheme and host) is used. Paths are ignored. The URL where the recipient can access the ceremony. You can share this link with the recipient directly or embed it in your application. This property is `null` when: - The ceremony uses `email_link` authentication. SignatureAPI delivers the URL by email in that case. - The ceremony is not active (for example, it is completed, revoked, or declined). The URL expires 30 days after creation, or when a new ceremony is created for the same recipient. Controls whether the completed deliverable is automatically emailed to this recipient. ValueDescription emailThe completed deliverable is delivered to this recipient by email. This is the default for signers. noneThe completed deliverable is not emailed. Your application is responsible for distributing the deliverable. The signature methods available to the signer. The first item in the array is shown as the default. OptionDescription typedThe signer types their name. It is pre-filled from the recipient's name property. drawnThe signer draws their signature using a mouse, stylus, or touchscreen. If not specified, both `typed` and `drawn` are available, with `typed` shown first. The time at which the recipient completed their required actions on the envelope (for example, signed or approved), in ISO 8601 format. Returns `null` if the recipient has not yet completed. The time at which the recipient's status last changed, in ISO 8601 format. Updates whenever the recipient transitions to a new status. ### Deprecated Fields How the ceremony is created for the recipient. Available options are `automatic` and `manual`. The default is `automatic`. This property is deprecated. Use the `ceremony` object on the recipient when creating an envelope to control ceremony creation. This property will continue to be supported for backwards compatibility. ### Preparer The unique identifier of the recipient. Recipient IDs use the `re_` prefix. The unique identifier of the envelope, in UUID format. The type of the recipient. Determines what actions the recipient can perform during the ceremony. TypeDescription signerSigns documents. Every envelope must have at least one signing recipient. approverReviews and approves documents without signing. preparerFills in document fields on behalf of another party. automatic_signerThe signature is applied automatically by the system. For preparers, the type is `preparer`. A unique identifier you assign to each recipient in the envelope. Use it to match recipients with the places they should interact with (such as signature fields) and to identify them in events and webhook notifications. The key must start with a lowercase letter. It can contain lowercase letters, numbers, and underscores. Maximum 32 characters. It must be unique within the envelope. The full name of the recipient. Appears in invitation emails and is pre-filled for typed signatures. The email address of the recipient. SignatureAPI emails the ceremony link to this address when the ceremony uses `email_link` authentication, and the completed deliverable when `delivery_type` is `email`. The current status of the recipient in the signing workflow. StatusDescription pendingThe envelope has not been sent to the recipient yet. This is the initial status. awaitingThe recipient is waiting for earlier recipients in the routing order to complete. sentThe invitation has been sent to the recipient. completedThe recipient has completed their required actions (for example, signed or approved). rejectedThe recipient declined to complete the envelope. soft_bouncedThe invitation email was temporarily undeliverable (for example, a full mailbox). You can resend the request. hard_bouncedThe invitation email was permanently undeliverable (for example, an invalid address). Use the Replace endpoint to assign a new recipient. failedAn error occurred and the invitation could not be sent. replacedThis recipient was replaced with a new one via the Replace endpoint. The current ceremony (/docs/api/resources/ceremonies/object) for the recipient. ### Ceremony ### Email Link Authentication With **email link authentication**, the recipient receives an email with a direct link to the ceremony. Clicking the link authenticates the recipient and opens the signing session. The type of authentication. Available values: `email_link`, `email_code`, and `custom`. For email link authentication, this value is `email_link`. The custom subject line used for this recipient's invitation email. `null` if the envelope title is used. The custom message body used for this recipient's invitation email. `null` if the envelope message is used. ### Email Code Authentication With **email code authentication**, the recipient receives an email from SignatureAPI containing a 9-digit code. The recipient must enter this code to authenticate and access the ceremony. The type of authentication. Available values: `email_link`, `email_code`, and `custom`. For email code authentication, this value is `email_code`. ### Custom Authentication With **custom authentication**, your application authenticates the recipient. SignatureAPI provides a ceremony URL that you share or embed in your application to give the recipient access. The type of authentication. Available values: `email_link`, `email_code`, and `custom`. For custom authentication, this value is `custom`. The name of your company or application that authenticated the recipient. This value appears in the envelope audit log as the authentication provider. Key-value pairs with metadata about the authentication event, such as timestamps, session IDs, and user identifiers. These values appear in the envelope audit log. The values in `data` must be sufficient to verify how the recipient was authenticated. You must retain all records needed to prove the recipient's authentication, such as session information. In cases such as legal proceedings, you may need to provide these records to confirm identity. Review our Terms & Conditions (/docs/legal/terms/terms) for details. An HTTPS URL to redirect the recipient to after the ceremony finishes. Learn more in Redirect URL (/docs/api/resources/ceremonies/redirect-url). The delay in seconds before the ceremony redirects to `redirect_url` (standalone ceremonies) or emits completion events (embedded ceremonies). Defaults to `3`. Allowed range: `0` to `20`. Learn more in Redirect URL (/docs/api/resources/ceremonies/redirect-url). The format of the ceremony URL. Available options: - `standard` (default): Full-length URL. Works for most use cases. - `short`: Shortened URL. Use this when sharing through space-constrained channels such as SMS or push notifications. Origins allowed to embed this ceremony in an iframe. These values set the `frame-ancestors` directive in the ceremony's Content Security Policy (CSP) header. Sources typically take the form of a scheme and host (for example, `https://app.example.com`). Wildcards are supported (for example, `https://*.example.com`). For all available options, see the frame-ancestors documentation (https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/frame-ancestors#sources). Defaults to an empty list (`[]`), which means embedding is not allowed. To allow embedding from all origins (not recommended for production), use `["*"]`. Only the origin (scheme and host) is used. Paths are ignored. The URL where the recipient can access the ceremony. You can share this link with the recipient directly or embed it in your application. This property is `null` when: - The ceremony uses `email_link` authentication. SignatureAPI delivers the URL by email in that case. - The ceremony is not active (for example, it is completed, revoked, or declined). The URL expires 30 days after creation, or when a new ceremony is created for the same recipient. Controls whether SignatureAPI emails the completed deliverable to the recipient once the envelope is finished. ValueDescription emailThe completed deliverable is delivered to this recipient by email. noneThe completed deliverable is not emailed. Your application is responsible for distributing the deliverable. This is the default for approvers and preparers. The time at which the recipient completed their required actions on the envelope (for example, signed or approved), in ISO 8601 format. Returns `null` if the recipient has not yet completed. The time at which the recipient's status last changed, in ISO 8601 format. Updates whenever the recipient transitions to a new status. ### Deprecated Fields How the ceremony is created for the recipient. Available options are `automatic` and `manual`. The default is `automatic`. This property is deprecated. Use the `ceremony` object on the recipient when creating an envelope to control ceremony creation. This property will continue to be supported for backwards compatibility. ### Approver The unique identifier of the recipient. Recipient IDs use the `re_` prefix. The unique identifier of the envelope, in UUID format. The type of the recipient. Determines what actions the recipient can perform during the ceremony. TypeDescription signerSigns documents. Every envelope must have at least one signing recipient. approverReviews and approves documents without signing. preparerFills in document fields on behalf of another party. automatic_signerThe signature is applied automatically by the system. For approvers, the type is `approver`. A unique identifier you assign to each recipient in the envelope. Use it to match recipients with the places they should interact with (such as signature fields) and to identify them in events and webhook notifications. The key must start with a lowercase letter. It can contain lowercase letters, numbers, and underscores. Maximum 32 characters. It must be unique within the envelope. The full name of the recipient. Appears in invitation emails and is pre-filled for typed signatures. The email address of the recipient. SignatureAPI emails the ceremony link to this address when the ceremony uses `email_link` authentication, and the completed deliverable when `delivery_type` is `email`. The current status of the recipient in the signing workflow. StatusDescription pendingThe envelope has not been sent to the recipient yet. This is the initial status. awaitingThe recipient is waiting for earlier recipients in the routing order to complete. sentThe invitation has been sent to the recipient. completedThe recipient has completed their required actions (for example, signed or approved). rejectedThe recipient declined to complete the envelope. soft_bouncedThe invitation email was temporarily undeliverable (for example, a full mailbox). You can resend the request. hard_bouncedThe invitation email was permanently undeliverable (for example, an invalid address). Use the Replace endpoint to assign a new recipient. failedAn error occurred and the invitation could not be sent. replacedThis recipient was replaced with a new one via the Replace endpoint. The current ceremony (/docs/api/resources/ceremonies/object) for the recipient. ### Ceremony ### Email Link Authentication With **email link authentication**, the recipient receives an email with a direct link to the ceremony. Clicking the link authenticates the recipient and opens the signing session. The type of authentication. Available values: `email_link`, `email_code`, and `custom`. For email link authentication, this value is `email_link`. The custom subject line used for this recipient's invitation email. `null` if the envelope title is used. The custom message body used for this recipient's invitation email. `null` if the envelope message is used. ### Email Code Authentication With **email code authentication**, the recipient receives an email from SignatureAPI containing a 9-digit code. The recipient must enter this code to authenticate and access the ceremony. The type of authentication. Available values: `email_link`, `email_code`, and `custom`. For email code authentication, this value is `email_code`. ### Custom Authentication With **custom authentication**, your application authenticates the recipient. SignatureAPI provides a ceremony URL that you share or embed in your application to give the recipient access. The type of authentication. Available values: `email_link`, `email_code`, and `custom`. For custom authentication, this value is `custom`. The name of your company or application that authenticated the recipient. This value appears in the envelope audit log as the authentication provider. Key-value pairs with metadata about the authentication event, such as timestamps, session IDs, and user identifiers. These values appear in the envelope audit log. The values in `data` must be sufficient to verify how the recipient was authenticated. You must retain all records needed to prove the recipient's authentication, such as session information. In cases such as legal proceedings, you may need to provide these records to confirm identity. Review our Terms & Conditions (/docs/legal/terms/terms) for details. An HTTPS URL to redirect the recipient to after the ceremony finishes. Learn more in Redirect URL (/docs/api/resources/ceremonies/redirect-url). The delay in seconds before the ceremony redirects to `redirect_url` (standalone ceremonies) or emits completion events (embedded ceremonies). Defaults to `3`. Allowed range: `0` to `20`. Learn more in Redirect URL (/docs/api/resources/ceremonies/redirect-url). The format of the ceremony URL. Available options: - `standard` (default): Full-length URL. Works for most use cases. - `short`: Shortened URL. Use this when sharing through space-constrained channels such as SMS or push notifications. Origins allowed to embed this ceremony in an iframe. These values set the `frame-ancestors` directive in the ceremony's Content Security Policy (CSP) header. Sources typically take the form of a scheme and host (for example, `https://app.example.com`). Wildcards are supported (for example, `https://*.example.com`). For all available options, see the frame-ancestors documentation (https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/frame-ancestors#sources). Defaults to an empty list (`[]`), which means embedding is not allowed. To allow embedding from all origins (not recommended for production), use `["*"]`. Only the origin (scheme and host) is used. Paths are ignored. The URL where the recipient can access the ceremony. You can share this link with the recipient directly or embed it in your application. This property is `null` when: - The ceremony uses `email_link` authentication. SignatureAPI delivers the URL by email in that case. - The ceremony is not active (for example, it is completed, revoked, or declined). The URL expires 30 days after creation, or when a new ceremony is created for the same recipient. Controls whether SignatureAPI emails the completed deliverable to the recipient once the envelope is finished. ValueDescription emailThe completed deliverable is delivered to this recipient by email. noneThe completed deliverable is not emailed. Your application is responsible for distributing the deliverable. This is the default for approvers and preparers. The time at which the recipient completed their required actions on the envelope (for example, signed or approved), in ISO 8601 format. Returns `null` if the recipient has not yet completed. The time at which the recipient's status last changed, in ISO 8601 format. Updates whenever the recipient transitions to a new status. ### Deprecated Fields How the ceremony is created for the recipient. Available options are `automatic` and `manual`. The default is `automatic`. This property is deprecated. Use the `ceremony` object on the recipient when creating an envelope to control ceremony creation. This property will continue to be supported for backwards compatibility. ### Automatic Signer The unique identifier of the recipient. Recipient IDs use the `re_` prefix. The unique identifier of the envelope, in UUID format. The type of the recipient. Determines what actions the recipient can perform during the ceremony. TypeDescription signerSigns documents. Every envelope must have at least one signing recipient. approverReviews and approves documents without signing. preparerFills in document fields on behalf of another party. automatic_signerThe signature is applied automatically by the system. For automatic signers, the type is `automatic_signer`. A unique identifier you assign to each recipient in the envelope. Use it to match recipients with the places they should interact with (such as signature fields) and to identify them in events and webhook notifications. The key must start with a lowercase letter. It can contain lowercase letters, numbers, and underscores. Maximum 32 characters. It must be unique within the envelope. The full name of the signer. Appears in the audit log line that records the automatic signature. The signature image applied to the document, as supplied at envelope creation. `null` if no preset signature was supplied. ### Preset symbol The symbol type. Currently only `drawn` is supported. The URL of the PNG upload referenced when the automatic signer was created. The initials image applied to the document, as supplied at envelope creation. `null` if no preset initials were supplied. Same shape as `signature`. A short statement explaining why the initiator was authorized to sign on behalf of this person. This string is shown as-is in the audit log. Maximum 500 characters. The current status of the recipient. An automatic signer transitions from `pending` or `awaiting` directly to `completed` once the envelope is released and the signature is applied. See recipient lifecycle (/docs/api/resources/recipients/lifecycle). The time at which the recipient's signature was applied, in ISO 8601 format. Returns `null` if the recipient has not yet completed. The time at which the recipient's status last changed, in ISO 8601 format. Automatic signers do not have `email`, `ceremony`, `delivery_type`, or `signature_options` properties. They do not receive invitations or access a ceremony. ```json Signer { "id": "re_26w2VVV5JVm4j459TY5BNM", "envelope_id": "52872f0e-b919-4d69-89cd-e7e56af00548", "type": "signer", "key": "client", "name": "Emily Johnson", "email": "emily@example.com", "status": "completed", "status_updated_at": "2025-12-31T15:00:00.000Z", "completed_at": "2025-12-31T15:00:00.000Z", "delivery_type": "email", "signature_options": ["typed", "drawn"], "ceremony": { "authentication": [ { "type": "email_link", "subject_override": null, "message_override": null } ], "redirect_url": null, "redirect_delay": 3, "embeddable_in": [], "url_variant": "standard", "url": null }, "ceremony_creation": "automatic" } ``` ```json Approver { "id": "re_7KpQVVV5JVm4j459TY5ABC", "envelope_id": "52872f0e-b919-4d69-89cd-e7e56af00548", "type": "approver", "key": "manager", "name": "Sarah Chen", "email": "sarah@example.com", "status": "completed", "status_updated_at": "2025-12-31T14:30:00.000Z", "completed_at": "2025-12-31T14:30:00.000Z", "delivery_type": "none", "ceremony": { "authentication": [ { "type": "email_link", "subject_override": null, "message_override": null } ], "redirect_url": null, "redirect_delay": 3, "embeddable_in": [], "url_variant": "standard", "url": null }, "ceremony_creation": "automatic" } ``` ```json Preparer { "id": "re_9XtRVVV5JVm4j459TY5DEF", "envelope_id": "52872f0e-b919-4d69-89cd-e7e56af00548", "type": "preparer", "key": "sales_rep", "name": "Alex Smith", "email": "alex@example.com", "status": "completed", "status_updated_at": "2025-12-31T14:00:00.000Z", "completed_at": "2025-12-31T14:00:00.000Z", "delivery_type": "none", "ceremony": { "authentication": [ { "type": "email_link", "subject_override": null, "message_override": null } ], "redirect_url": null, "redirect_delay": 3, "embeddable_in": [], "url_variant": "standard", "url": null }, "ceremony_creation": "automatic" } ``` ```json Automatic Signer { "id": "re_3MnSVVV5JVm4j459TY5GHI", "envelope_id": "52872f0e-b919-4d69-89cd-e7e56af00548", "type": "automatic_signer", "key": "dr_doe", "name": "Dr. John Doe", "signature": { "type": "drawn", "url": "https://api.signatureapi.com/v1/uploads/upl_1sAAaVfabdt0esVjmSTmLA" }, "initials": { "type": "drawn", "url": "https://api.signatureapi.com/v1/uploads/upl_2tBBbWgbcdeu1fsWknUnNB" }, "mandate": "With permission given and recorded on Jan 1 2026", "status": "completed", "status_updated_at": "2025-12-31T15:05:00.000Z", "completed_at": "2025-12-31T15:05:00.000Z" } ``` ## Recipient lifecycle URL: https://signatureapi.com/docs/api/resources/recipients/lifecycle Description: Track recipient status through pending, awaiting, sent, completed, and other states The `status` property on a recipient indicates where the recipient is in the signing workflow. Status changes happen automatically as the envelope progresses. ## Status reference | Status | Description | |--------|-------------| | `pending` | The envelope has not been sent to the recipient yet. This is the initial status when an envelope is created. | | `awaiting` | The recipient is waiting for one or more earlier recipients to complete. Applies to sequential routing only. | | `sent` | The invitation has been sent to the recipient. The recipient has not yet completed their ceremony. | | `completed` | The recipient has finished all required actions (for example, signed or approved). | | `rejected` | The recipient declined to complete the envelope. | | `soft_bounced` | The invitation email was temporarily undeliverable (for example, a full mailbox). You can resend the request using the Resend (/docs/api/resources/recipients/resend) endpoint. | | `hard_bounced` | The invitation email was permanently undeliverable (for example, an invalid address). Use the Replace (/docs/api/resources/recipients/replace) endpoint to assign a different recipient. | | `failed` | An error prevented the email from being sent. | | `replaced` | This recipient was replaced by a new one using the Replace endpoint. | ## Typical flow For an envelope with sequential routing and a single signer, the recipient moves through these statuses in order: 1. **`pending`** - The envelope is created. The recipient has been registered but not yet notified. 2. **`sent`** - The envelope starts processing and the invitation email is sent. 3. **`completed`** - The recipient finishes their ceremony. When an envelope has multiple recipients with sequential routing, later recipients wait in **`awaiting`** status until all earlier recipients complete. ## Handling delivery problems Two statuses indicate email delivery problems: **`soft_bounced`** means the email was temporarily rejected. The recipient's address may be valid. Use the Resend (/docs/api/resources/recipients/resend) endpoint to try again. **`hard_bounced`** means the email was permanently rejected. The address is likely invalid. Use the Replace (/docs/api/resources/recipients/replace) endpoint to assign a new recipient with a valid address. ## Monitoring status changes Listen for recipient events (/docs/api/resources/events/recipient) to receive real-time notifications when a recipient's status changes. You can also poll the Get a recipient (/docs/api/resources/recipients/get) endpoint to check the current status at any time. ## Recipient routing URL: https://signatureapi.com/docs/api/resources/envelopes/routing Description: Control signing order with sequential or parallel recipient routing options The `routing` property controls the order in which recipients receive and act on the envelope. Two options are available: `sequential` and `parallel`. The default is `sequential`. ## Sequential routing With sequential routing, the envelope is delivered to one recipient at a time, in the order listed in the `recipients` array. Each recipient must complete their part before the next one is notified. Image: (/docs/images/routing-sequential.png) - Recipients act in the order defined in the `recipients` array. - Each recipient must complete before the next one is notified. - Recipients acting later can see signatures and data entered by those who acted before them. - Recipients waiting for a previous recipient will have a status of `awaiting`. - Use this when the order of signatures matters. ## Parallel routing With parallel routing, all recipients receive the envelope at the same time and can act in any order. Image: (/docs/images/routing-parallel.png) - All recipients are notified simultaneously. - Recipients can act in any order. - Use this when signing order does not matter. ## Setting routing on an envelope Set the `routing` property when creating an envelope. If omitted, sequential routing is used. ```json // POST https://api.signatureapi.com/v1/envelopes // X-API-Key: key_test_... // Content-Type: application/json { "title": "Service Agreement", "routing": "parallel", "documents": [ //... ], "recipients": [ //... ] } ``` ## Recipient Authentication URL: https://signatureapi.com/docs/api/resources/ceremonies/authentication/overview Description: Choose how recipients verify their identity before accessing a signing ceremony. Before a recipient can access a ceremony (/docs/api/resources/ceremonies/object), they must authenticate. SignatureAPI supports three authentication methods that you can use individually or combine for added security. ## Authentication methods ### Email Link (default) SignatureAPI sends the recipient an email with a direct link. Clicking the link authenticates the recipient automatically. - No setup required. Works out of the box. - Simplest experience for recipients. - Ceremonies are created and emails sent automatically when you create an envelope. Learn more about Email Link Authentication (/docs/api/resources/ceremonies/authentication/email-link) ### Email Code SignatureAPI sends the recipient an email with a 9-digit verification code. The recipient enters the code to authenticate. - Confirms the recipient has access to their email account. - As the first method, you receive the ceremony URL to share through your own channels, over SMS, app notifications, or direct links. - After `email_link`, SignatureAPI still emails the invitation and the code becomes a second step. Learn more about Email Code Authentication (/docs/api/resources/ceremonies/authentication/email-code) ### Custom Your application authenticates the recipient. SignatureAPI provides a ceremony URL that you share directly or embed in your application. - Use your existing authentication systems. - Supports embedded signing experiences. - Your authentication details are recorded in the audit log. Learn more about Custom Authentication (/docs/api/resources/ceremonies/authentication/custom) ### Multiple methods Combine authentication methods for enhanced security. Recipients complete each method in sequence before accessing the ceremony. The first method decides who delivers the ceremony URL, so `[email_link, email_code]` has SignatureAPI email the invitation link and the verification code, with no email sent by your application. Learn more about Multiple Authentication Methods (/docs/api/resources/ceremonies/authentication/multiple) ## How to create a ceremony You can create a ceremony in two ways: automatically when creating an envelope, or manually using the Create Ceremony endpoint. ### On envelope creation (automatic) Pass a `ceremony` object on each recipient when creating an envelope. SignatureAPI creates the ceremony immediately. If you omit `ceremony`, SignatureAPI uses email link authentication by default. ```json Email Link (default) // POST https://api.signatureapi.com/v1/envelopes // X-API-Key: key_test_... // Content-Type: application/json { "title": "Service Agreement", "recipients": [ { "type": "signer", "key": "client", "name": "John Doe", "email": "john.doe@example.com" } ], "documents": [ /* ... */ ] } ``` ```json Email Code // POST https://api.signatureapi.com/v1/envelopes // X-API-Key: key_test_... // Content-Type: application/json { "title": "Service Agreement", "recipients": [ { "type": "signer", "key": "client", "name": "John Doe", "email": "john.doe@example.com", "ceremony": { "authentication": [ { "type": "email_code" } ] } } ], "documents": [ /* ... */ ] } ``` ```json Custom // POST https://api.signatureapi.com/v1/envelopes // X-API-Key: key_test_... // Content-Type: application/json { "title": "Service Agreement", "recipients": [ { "type": "signer", "key": "client", "name": "John Doe", "email": "john.doe@example.com", "ceremony": { "authentication": [ { "type": "custom", "provider": "SuperApp", "data": { "Session ID": "a4f9e8b2-7c1d-4b2d-9a4b-e0c5d6f7a1b3", "Logged In At": "2026-12-31T23:59:59Z" } } ] } } ], "documents": [ /* ... */ ] } ``` ```json Multiple methods // POST https://api.signatureapi.com/v1/envelopes // X-API-Key: key_test_... // Content-Type: application/json { "title": "Service Agreement", "recipients": [ { "type": "signer", "key": "client", "name": "John Doe", "email": "john.doe@example.com", "ceremony": { "authentication": [ { "type": "custom", "provider": "SuperApp", "data": { "Session ID": "a4f9e8b2-7c1d-4b2d-9a4b-e0c5d6f7a1b3", "Logged In At": "2026-12-31T23:59:59Z" } }, { "type": "email_code" } ] } } ], "documents": [ /* ... */ ] } ``` ### Create Ceremony endpoint (manual) Use the Create Ceremony (/docs/api/resources/ceremonies/create) endpoint after the envelope is created. This lets you change authentication methods or create new access for the same recipient. Creating a new ceremony automatically revokes any previous ceremony for that recipient. Only the most recent ceremony remains active. Common use cases: - Switch from custom authentication to email link if the recipient hasn't signed within a set time. - Provide a new URL after the original one expires. - Update ceremony settings like the redirect URL. ```json Email Link // POST https://api.signatureapi.com/v1/recipients/{recipient_id}/ceremonies // X-API-Key: key_test_... // Content-Type: application/json { "authentication": [ { "type": "email_link" } ] } ``` ```json Email Code // POST https://api.signatureapi.com/v1/recipients/{recipient_id}/ceremonies // X-API-Key: key_test_... // Content-Type: application/json { "authentication": [ { "type": "email_code" } ] } ``` ```json Custom // POST https://api.signatureapi.com/v1/recipients/{recipient_id}/ceremonies // X-API-Key: key_test_... // Content-Type: application/json { "authentication": [ { "type": "custom", "provider": "SuperApp", "data": { "Session ID": "a4f9e8b2-7c1d-4b2d-9a4b-e0c5d6f7a1b3", "Logged In At": "2026-12-31T23:59:59Z" } } ] } ``` ```json Multiple // POST https://api.signatureapi.com/v1/recipients/{recipient_id}/ceremonies // X-API-Key: key_test_... // Content-Type: application/json { "authentication": [ { "type": "custom", "provider": "SuperApp", "data": { "Session ID": "a4f9e8b2-7c1d-4b2d-9a4b-e0c5d6f7a1b3", "Logged In At": "2026-12-31T23:59:59Z" } }, { "type": "email_code" } ] } ``` ## Email Link Authentication URL: https://signatureapi.com/docs/api/resources/ceremonies/authentication/email-link Description: Authenticate recipients with a secure link sent to their email address. With email link authentication, SignatureAPI sends the recipient (/docs/api/resources/recipients/object) an email with a direct link. Clicking the link authenticates the recipient and opens their signing session. This is the default authentication method. If you don't specify a ceremony configuration, SignatureAPI uses email link authentication automatically. ## When to use Email link authentication works well when: - You want the simplest experience for recipients. - Recipients check email to access documents. - You don't need to control the ceremony URL or deliver it through other channels. - Your security requirements allow email-based authentication. ## Creating an email link ceremony You can create an email link ceremony automatically when creating an envelope, or manually using the Create Ceremony endpoint. ### On envelope creation (automatic) By default, SignatureAPI creates an email link ceremony and sends the invitation email when you create an envelope. ```json // POST https://api.signatureapi.com/v1/envelopes // X-API-Key: key_test_... // Content-Type: application/json { "title": "Service Agreement", "recipients": [ { "type": "signer", "key": "client", "name": "John Doe", "email": "john.doe@example.com" } ], "documents": [ /* ... */ ] } ``` To add ceremony options such as a redirect URL, set the `ceremony` property explicitly. ```json // POST https://api.signatureapi.com/v1/envelopes // X-API-Key: key_test_... // Content-Type: application/json { "title": "Service Agreement", "recipients": [ { "type": "signer", "key": "client", "name": "John Doe", "email": "john.doe@example.com", "ceremony": { "authentication": [ { "type": "email_link" } ], "redirect_url": "https://www.example.com/redirect" } } ], "documents": [ /* ... */ ] } ``` ### Create Ceremony endpoint (manual) Use the Create Ceremony (/docs/api/resources/ceremonies/create) endpoint to create an email link ceremony after the envelope is created. Creating a new ceremony automatically revokes any previous ceremony for that recipient. Only the most recent ceremony remains active. ```json // POST https://api.signatureapi.com/v1/recipients/{recipient_id}/ceremonies // X-API-Key: key_test_... // Content-Type: application/json { "authentication": [ { "type": "email_link" } ] } ``` ## Email customization By default, SignatureAPI derives the email content from the envelope: - Subject: `envelope.title` - Message body: `envelope.message` - Language: `envelope.language` For example, an envelope with: ```json { "title": "Dummy Agreement", "message": "Please take a moment to review the attached agreement. Once you complete your electronic signature, a signed copy will be sent to your email.\n\nIf you have questions, feel free to reach out." } ``` produces an email similar to this: Image: (/docs/api/resources/ceremonies/authentication/email-example.png) ### Per-recipient overrides Use `subject_override` and `message_override` on the `email_link` authentication object to customize the email for a specific recipient. ```json // POST https://api.signatureapi.com/v1/envelopes // X-API-Key: key_test_... // Content-Type: application/json { "title": "Service Agreement", "recipients": [ { "type": "signer", "key": "client", "name": "John Doe", "email": "john.doe@example.com", "ceremony": { "authentication": [ { "type": "email_link", "subject_override": "Action Required: Please sign the Service Agreement", "message_override": "Dear John,\n\nPlease review and sign the attached Service Agreement at your earliest convenience." } ] } } ], "documents": [ /* ... */ ] } ``` `message_override` supports Markdown formatting: `**bold**`, `*italic*`, and `\n\n` for paragraph breaks. To send invitation emails through your own infrastructure with custom branding, use Custom Authentication (/docs/api/resources/ceremonies/authentication/custom) to obtain the ceremony URL and deliver it yourself. ## Audit log When a recipient clicks the email link, SignatureAPI records the timestamp. The audit log entry looks like this: 12/31/2025 11:59:59 PM John Doe (#7161cf07) has authenticated using a secure link sent to john⁠@example.com. ## Email Code Authentication URL: https://signatureapi.com/docs/api/resources/ceremonies/authentication/email-code Description: Authenticate recipients with a verification code sent to their email address. With email code authentication, SignatureAPI sends the recipient (/docs/api/resources/recipients/object) an email containing a 9-digit verification code. The recipient enters this code to authenticate and access their signing ceremony. ## When to use Email code authentication is useful when: - You want to share the ceremony URL through your own channels (SMS, app notifications, direct links). - Recipients are in environments where email links may be blocked by security policies. - You want to embed the ceremony in your application while still using email-based authentication. - You want SignatureAPI to email the invitation as usual, with a verification code as a second step. ## Who delivers the ceremony URL `authentication` is an ordered array, and its **first** method decides who delivers the ceremony URL. Email code behaves differently depending on where you place it: | `authentication` | Invitation email | `url` in the response | | --- | --- | --- | | `[email_code]` | None. You deliver the URL. | Returned | | `[email_link, email_code]` | Sent by SignatureAPI | `null` | | `[custom, email_code]` | None. You deliver the URL. | Returned | Placing `email_code` after `email_link` keeps SignatureAPI responsible for both emails — the invitation link and the code — so your application sends neither. See Multiple Authentication Methods (/docs/api/resources/ceremonies/authentication/multiple) for that combination. The rest of this page describes `email_code` as the **first** method, where you deliver the URL yourself. ## How it works ### Configure the ceremony Create an envelope or call the Create Ceremony endpoint with `email_code` as the first authentication method. The API returns the ceremony URL. ### Deliver the URL Share the ceremony URL with the recipient through your chosen channel (email, SMS, in-app link, etc.). ### Recipient enters code When the recipient opens the URL, SignatureAPI prompts them to verify their email. After they click the verification button, SignatureAPI sends them a 9-digit code by email. ### Authentication complete The recipient enters the code. Once verified, they can proceed with signing. ## Creating an email code ceremony ### On envelope creation (automatic) Set the recipient's ceremony authentication to `email_code` when creating the envelope. Because it is the first method, the ceremony URL is returned in the response. ```json // POST https://api.signatureapi.com/v1/envelopes // X-API-Key: key_test_... // Content-Type: application/json { "title": "Service Agreement", "recipients": [ { "type": "signer", "key": "client", "name": "John Doe", "email": "john.doe@example.com", "ceremony": { "authentication": [ { "type": "email_code" } ] } } ], "documents": [ /* ... */ ] } ``` The response includes `ceremony.url` for each recipient: ```json Response (excerpt) { "id": "abcdef12-3456-7890-1234-abcdef123456", "title": "Service Agreement", "recipients": [ { "type": "signer", "key": "client", "name": "John Doe", "email": "john.doe@example.com", "ceremony": { "authentication": [ { "type": "email_code" } ], "url": "https://sign.signatureapi.com/en/start?token=eyJhbGcNiIsInR..." } } ] } ``` ### Create Ceremony endpoint (manual) Use the Create Ceremony (/docs/api/resources/ceremonies/create) endpoint to create an email code ceremony after the envelope is created. Creating a new ceremony automatically revokes any previous ceremony for that recipient. Only the most recent ceremony remains active. ```json // POST https://api.signatureapi.com/v1/recipients/{recipient_id}/ceremonies // X-API-Key: key_test_... // Content-Type: application/json { "authentication": [ { "type": "email_code" } ] } ``` The `url` property in the response is the ceremony URL to deliver to the recipient. It is `null` instead when `email_link` is the first method. ```json // HTTP/1.1 201 Created { "authentication": [ { "type": "email_code" } ], "embeddable_in": [], "redirect_url": null, "redirect_delay": 3, "url_variant": "standard", "url": "https://sign.signatureapi.com/en/start?token=eyJhbGcNiIsInR..." } ``` ## Recipient experience ### Email verification prompt The recipient opens the ceremony URL and is asked to verify their email address. Image: Email verification prompt (/docs/api/resources/ceremonies/authentication/email-code/email-code-1.png) ### Code sent by email After the recipient clicks to verify, SignatureAPI sends them an email with the 9-digit code. Image: Email with code (/docs/api/resources/ceremonies/authentication/email-code/email-code-2.png) In test mode, no emails are sent. You can view the verification codes that would have been sent in the SignatureAPI dashboard under ceremony details. ### Code entry The recipient enters the code in the ceremony interface. Image: Code entry interface (/docs/api/resources/ceremonies/authentication/email-code/email-code-3.png) ### Access granted After the correct code is entered, the recipient can proceed with signing. Image: Successful verification (/docs/api/resources/ceremonies/authentication/email-code/email-code-5.png) ## Audit log When the recipient enters the verification code, SignatureAPI records the timestamp. The audit log entry looks like this: 12/31/2025 11:59:59 PM John Doe (#7161cf07) has authenticated using a verification code sent to john⁠@example.com. ## Custom Authentication URL: https://signatureapi.com/docs/api/resources/ceremonies/authentication/custom Description: Use your own authentication system to verify recipients before they access the signing ceremony. With custom authentication, your application or workflow authenticates the recipient (/docs/api/resources/recipients/object). SignatureAPI provides a ceremony URL that you share directly with the recipient to start their signing session. ## When to use Custom authentication is the right choice when: - Recipients are already authenticated in your system. - You want to integrate signing into your existing application flow. - You need specific authentication methods (biometrics, SSO, multi-factor). - You want to embed the ceremony in your application. After creating the ceremony, you can: - Send the URL via email or SMS with your own branding. - Redirect the recipient directly to the ceremony. - Embed the ceremony in your application interface. - Include the URL in push notifications. ## Creating a custom authentication ceremony ### On envelope creation (automatic) Set the recipient's ceremony authentication to `custom` when creating the envelope. Include your authentication details in the `provider` and `data` properties. ```json // POST https://api.signatureapi.com/v1/envelopes // X-API-Key: key_test_... // Content-Type: application/json { "title": "Service Agreement", "recipients": [ { "type": "signer", "key": "client", "name": "John Doe", "email": "john.doe@example.com", "ceremony": { "authentication": [ { "type": "custom", "provider": "SuperApp", "data": { "Session ID": "a4f9e8b2-7c1d-4b2d-9a4b-e0c5d6f7a1b3", "Authenticated At": "2025-12-31T23:59:59Z" } } ] } } ], "documents": [ /* ... */ ] } ``` The response includes `ceremony.url` for each recipient: ```json Response (excerpt) { "id": "abcdef12-3456-7890-1234-abcdef123456", "title": "Service Agreement", "recipients": [ { "type": "signer", "key": "client", "ceremony": { "authentication": [ { "type": "custom", "provider": "SuperApp", "data": { "Session ID": "a4f9e8b2-7c1d-4b2d-9a4b-e0c5d6f7a1b3", "Authenticated At": "2025-12-31T23:59:59Z" } } ], "url": "https://sign.signatureapi.com/en/start?token=eyJhbGcNiIsInR..." } } ] } ``` ### Create Ceremony endpoint (manual) Use the Create Ceremony (/docs/api/resources/ceremonies/create) endpoint to create a custom authentication ceremony after the envelope is created. Creating a new ceremony automatically revokes any previous ceremony for that recipient. Only the most recent ceremony remains active. ```json // POST https://api.signatureapi.com/v1/recipients/{recipient_id}/ceremonies // X-API-Key: key_test_... // Content-Type: application/json { "authentication": [ { "type": "custom", "provider": "SuperApp", "data": { "Session ID": "a4f9e8b2-7c1d-4b2d-9a4b-e0c5d6f7a1b3", "Authenticated At": "2025-12-31T23:59:59Z" } } ] } ``` The `url` property in the response is the ceremony URL to deliver to the recipient. ```json // HTTP/1.1 201 Created { "authentication": [ { "type": "custom", "provider": "SuperApp", "data": { "Session ID": "a4f9e8b2-7c1d-4b2d-9a4b-e0c5d6f7a1b3", "Authenticated At": "2025-12-31T23:59:59Z" } } ], "embeddable_in": [], "redirect_url": null, "redirect_delay": 3, "url_variant": "standard", "url": "https://sign.signatureapi.com/en/start?token=eyJhbGcNiIsInR..." } ``` ## Authentication provider Set `provider` to the name of the company or application that authenticated the recipient. This value appears in the audit log: > John Doe has been authenticated by [Provider Name] ## Authentication data The `data` property holds key-value pairs that link the ceremony to your authentication records. These values appear in the envelope audit log. The values in `data` must be sufficient to verify how the recipient was authenticated. In edge cases such as legal proceedings, you may need to provide your internal records to confirm the recipient's identity. When using custom authentication, retain all records necessary to prove authentication. Review our Terms & Conditions (/docs/legal/terms/terms) for details. Useful data to include: - **Session data:** Session IDs and session start timestamps that link to your authentication records. - **User identification:** Email addresses, phone numbers, or user IDs from your system. - **Authentication method:** The method used (OTP, biometrics, SSO) and relevant details like device IDs or IP addresses. - **Transaction references:** Hashes, nonces, or other unique identifiers. Example with rich authentication data: ```json { "type": "custom", "provider": "SuperApp", "data": { "Session ID": "a4f9e8b2-7c1d-4b2d-9a4b-e0c5d6f7a1b3", "Order Reference": "25005", "Authentication Timestamp": "2025-12-31T10:00:00Z", "Authentication Method": "SMS", "Phone Number": "+1-111-1111111", "IP Address": "100.100.100.100" } } ``` Review the values in `data` carefully. Do not include unnecessary sensitive information. ## Using the ceremony URL After creating the ceremony, you receive the URL. You can: - Send a customized email using your own domain and branding. - Embed the ceremony in your application. - Redirect the recipient from your application directly to the ceremony. Treat ceremony URLs as sensitive credentials. Do not expose them in public forums or share them with unauthorized users. ## Audit log When a recipient accesses a ceremony using custom authentication, SignatureAPI records the timestamp, provider, and authentication data. The audit log entry looks like this: 12/31/2025 11:59:59 PM John Doe (#7161cf07) has been authenticated by SuperApp: Session ID: a4f9e8b2-7c1d-4b2d-9a4b-e0c5d6f7a1b3 Order Reference: 25005 Authenticated At: Dec 31, 2025 23:59:59 Authentication Method: SMS Phone Number: +1-111-1111111 IP Address: 100.100.100.100 As provided by the initiator of the electronic signature transaction. ## Multiple Authentication Methods URL: https://signatureapi.com/docs/api/resources/ceremonies/authentication/multiple Description: Combine authentication methods to require recipients to complete more than one verification step. You can combine multiple authentication methods in a single ceremony. Recipients must complete each method in sequence before accessing the ceremony. ## Rules Not all combinations are valid. The table below shows which methods can appear at each position. A method marked `No` for later steps can still be combined with others — it just has to come first. | Method | First step | Second step and beyond | |--------|:----------:|:----------------------:| | Email Link (/docs/api/resources/ceremonies/authentication/email-link) | Yes | No | | Email Code (/docs/api/resources/ceremonies/authentication/email-code) | Yes | Yes | | Custom (/docs/api/resources/ceremonies/authentication/custom) | Yes | No | Additional constraints: - A ceremony supports a maximum of 5 authentication methods. - `email_link` and `custom` can each only be used as the first step. - `email_link` and `custom` cannot be combined together. - `email_code` can appear at most once in a ceremony. ## The first method decides who delivers the URL Whichever methods you combine, the **first** one determines how the recipient reaches the ceremony: - `email_link` first: SignatureAPI emails the link, and the ceremony's `url` property is `null`. This does not change when other methods follow it. - `email_code` or `custom` first: the `url` property is returned in the response, and your application delivers it. Methods after the first are challenges the recipient completes inside the ceremony. They never change who delivers the URL. ## Common combinations ### Custom + Email Code Your application authenticates the recipient first. SignatureAPI then independently verifies the recipient's identity by sending a code to their email. Use this combination when you want to authenticate recipients in your own system and also require a second factor that SignatureAPI controls. ```json // POST https://api.signatureapi.com/v1/recipients/{recipient_id}/ceremonies // X-API-Key: key_test_... // Content-Type: application/json { "authentication": [ { "type": "custom", "provider": "SuperApp", "data": { "Session ID": "a4f9e8b2-7c1d-4b2d-9a4b-e0c5d6f7a1b3", "Authenticated At": "2026-01-15T10:30:00Z" } }, { "type": "email_code" } ] } ``` Recipient experience: ### Authentication in your app The recipient authenticates in your system (custom authentication). ### Access the ceremony You direct the recipient to the ceremony URL or embed the ceremony in your app. ### Email verification SignatureAPI prompts for additional email verification. ### Code entry The recipient enters the 9-digit code from their email. ### Signing The recipient proceeds to sign documents. ### Email Link + Email Code SignatureAPI sends the invitation email automatically. When the recipient opens the ceremony, they must also enter an email verification code. Use this combination when you want SignatureAPI to handle delivery but also need a second verification step inside the ceremony, for example to meet compliance requirements. SignatureAPI sends both emails — the invitation link and the verification code — so your application sends none. Because `email_link` is first, the ceremony's `url` property is `null`. ```json // POST https://api.signatureapi.com/v1/recipients/{recipient_id}/ceremonies // X-API-Key: key_test_... // Content-Type: application/json { "authentication": [ { "type": "email_link" }, { "type": "email_code" } ] } ``` Recipient experience: ### Email link The recipient clicks the ceremony link in the email sent by SignatureAPI. ### Email verification SignatureAPI prompts for a second verification step. ### Code entry The recipient enters the 9-digit code from their email. ### Signing The recipient proceeds to sign documents. ## Signer URL: https://signatureapi.com/docs/api/resources/recipients/signer Description: A recipient type who must add their signature or initials to complete the document A **signer** is a recipient who reviews documents and adds their signature or initials. Every envelope must have at least one signer. A signer's signature can serve different purposes depending on the document: - Create legal obligations - Serve as evidence of intent - Confirm knowledge and understanding - Authorize specific actions or commitments ## The signer's ceremony The signer interacts with the envelope through the **signer's ceremony**, a guided session where they complete all required signing actions. At the start of the ceremony, the signer must consent to using electronic signatures. This consent is legally required in most jurisdictions for electronic signatures to be valid. Image: Consent screen (https://whimuc.com/QQDubRnfFPHF1uvj5mB5n8/fvhAEiNNi94cj.png) After consenting, the signer reviews the documents. If input places are assigned to the signer (such as text boxes or checkboxes), the signer fills them in. When ready, the signer clicks the place where their signature or initials is expected. Image: Signature place (https://whimuc.com/QQDubRnfFPHF1uvj5mB5n8/6S9QW9w1uMpza9.png) The signer chooses how to sign: by typing their name or by drawing their signature. The signer adopts this symbol as their signature. Image: Signature input (https://whimuc.com/QQDubRnfFPHF1uvj5mB5n8/Bj4WQGctPBjV4C.png) When a signer has more than one signature field, the adopt dialog can offer a checkbox to use the signature for all of them at once. Initials work the same way, with their own checkbox. This option is off by default. Want signers to sign all their fields at once? Contact support (mailto:support@signatureapi.com) to turn the checkbox on for your account. After completing all required places, the signer clicks **Finalize** to finish the ceremony. All steps of the signer's ceremony are recorded in the audit log. This log is attached to the signed documents in the deliverable. Image: Audit log (https://whimuc.com/QQDubRnfFPHF1uvj5mB5n8/6NWAK3FDZCtqzS.png) ## Workflow example ### Create an envelope Include one or more signer recipients. Assign signature places to each signer. ### Signer receives the invitation The signer receives an email invitation (if the ceremony uses `email_link` authentication) or accesses the ceremony URL directly. ### Signer completes their ceremony The signer consents to electronic signatures, reviews documents, fills in any input places, and adds their signature. ### Envelope completes Once all signers have finished, the envelope transitions to `completed` status and a deliverable is generated. ## Creating an envelope with a signer Specify `"type": "signer"` for recipients who must sign the document. ```json // POST https://api.signatureapi.com/v1/envelopes // X-API-Key: key_test_... // Content-Type: application/json { "title": "Service Agreement", "recipients": [ { "key": "client", "type": "signer", "name": "Jordan Lee", "email": "jordan@example.com" } ], //... } ``` ## Assigning places to a signer Places are assigned to a signer using the `recipient_key` property. A signer must have at least one signature or initials place. Signers can also have text inputs, checkboxes, and other place types assigned. ```json { "documents": [ { "places": [ { "type": "signature", "recipient_key": "client", "key": "client_signature", //... }, { "type": "text_input", "recipient_key": "client", "key": "client_title", //... } ], //... } ], //... } ``` ## Delivery type The `delivery_type` property controls whether the completed deliverable is automatically emailed to the signer. The default is `email`. Set `delivery_type` to `none` when your application distributes the signed documents itself. This is common when embedding the ceremony in your web app (/docs/api/guides/how-to/embed-web) or delivering signing links via SMS (/docs/api/guides/use-cases/sms-signing-link). ```json { "recipients": [ { "type": "signer", "key": "client", "name": "Jordan Lee", "email": "jordan@example.com", "delivery_type": "none", //... } ], //... } ``` ## Signature options The `signature_options` array controls which signing methods are available. The first item in the array is shown as the default. | Option | Description | |--------|-------------| | `typed` | The signer types their name. It is pre-filled from the recipient's `name` property. | | `drawn` | The signer draws their signature using a mouse, stylus, or touchscreen. | Both options are enabled by default, with `typed` shown first. To allow only drawn signatures, set `signature_options` to `["drawn"]`. ## Next steps - Recipient lifecycle (/docs/api/resources/recipients/lifecycle) - Understand recipient status transitions - Create a ceremony (/docs/api/resources/ceremonies/create) - Customize how the signer accesses the envelope - Approver (/docs/api/resources/recipients/approver) - Add a reviewer who approves without signing - Preparer (/docs/api/resources/recipients/preparer) - Add a recipient who fills in fields before signing - Create an envelope (/docs/api/resources/envelopes/create) - Include signers in a new envelope ## Approver URL: https://signatureapi.com/docs/api/resources/recipients/approver Description: A recipient type who reviews and approves documents without adding a signature An **approver** is a recipient who reviews and approves documents without adding a signature. Approvers can fill in input places, but they cannot add signatures or initials. Use approvers for workflows that need a review or authorization step before the document reaches a signer. Common examples include: - Manager approval before a contract is sent to an external party - Compliance review before finalization - Internal sign-off where a formal signature is not required - Multi-stage approval workflows with different levels of authorization Approvers are functionally equivalent to preparers (/docs/api/resources/recipients/preparer). The difference is in the wording shown during the ceremony. Approvers see "Approve" as the final action. Preparers see "Finish". ## Approver vs. signer | | Approver | Signer | |--|--|--| | Reviews documents | Yes | Yes | | Fills in input places | Yes | Yes | | Adds signature or initials | No | Yes | | Recorded in audit log | No | Yes | | Recipient type | `approver` | `signer` | Use an approver when someone needs to authorize a document without creating a signature record. Use a signer when a legally binding signature is required. ## The approver's ceremony The approver accesses the envelope through the **approver's ceremony**. The approver reviews the documents and fills in any input places assigned to them, such as text boxes or checkboxes. After completing all required actions, the approver clicks **Approve**. Image: Approve button (/docs/images/approve-button.png) A confirmation screen appears once the approval is complete. Image: Approved confirmation (/docs/images/approved-confirmation.png) Approver actions are not recorded in the audit log. Only signer actions appear in the audit log attached to the deliverable. ## Workflow example ### Create an envelope Include an approver recipient before any signers in the recipient list. ### Approver completes their ceremony The approver reviews the documents and fills in any assigned input places. ### Subsequent recipients see the data Recipients who act after the approver see the document with the approver's fields already filled in. ### Signers complete signing Signers review the approved document and add their signatures. ## Creating an envelope with an approver Specify `"type": "approver"` for recipients who should review and approve without signing. Use sequential routing so the approver acts before the signer. ```json // POST https://api.signatureapi.com/v1/envelopes // X-API-Key: key_test_... // Content-Type: application/json { "title": "Service Agreement", "recipients": [ { "key": "manager", "type": "approver", "name": "Sarah Chen", "email": "sarah@company.com" }, { "key": "client", "type": "signer", "name": "Michael Torres", "email": "michael@client.com" } ], "routing": "sequential", //... } ``` In this example, the manager reviews and approves the agreement first. Then the client receives the document to sign. ## Assigning places to an approver Approvers can fill in text inputs, checkboxes, and dropdowns. Assign places to an approver using the `recipient_key` property. Signature and initials places cannot be assigned to approvers. ```json { "documents": [ { "places": [ { "type": "text_input", "recipient_key": "manager", "key": "approval_notes", //... }, { "type": "checkbox", "recipient_key": "manager", "key": "terms_reviewed", //... } ], //... } ], //... } ``` The values the approver enters are visible to recipients who act after them. ## Delivery The `delivery_type` controls whether SignatureAPI emails the completed deliverable to the approver. It defaults to `none`, so the approver does not receive the deliverable. Set it to `email` if you want them to receive it. The approver receives an email with the ceremony link when their ceremony uses `email_link` authentication, which is the default. To share the ceremony URL yourself instead, create the ceremony with `custom` authentication (/docs/api/guides/how-to/custom-authentication). ## Next steps - Recipient lifecycle (/docs/api/resources/recipients/lifecycle) - Understand recipient status transitions - Create a ceremony (/docs/api/resources/ceremonies/create) - Customize how the approver accesses the envelope - Signer (/docs/api/resources/recipients/signer) - Add a recipient who signs documents - Preparer (/docs/api/resources/recipients/preparer) - Add a recipient who fills in fields before signing - Create an envelope (/docs/api/resources/envelopes/create) - Include approvers in a new envelope ## Preparer URL: https://signatureapi.com/docs/api/resources/recipients/preparer Description: A recipient type who fills in document fields on behalf of other signers A **preparer** is a recipient who fills in document fields before the envelope reaches a signer. Preparers can complete text inputs, checkboxes, and dropdowns, but they cannot add signatures or initials. Use preparers when someone needs to populate document data before a signer receives the envelope. Common examples include: - A sales representative entering pricing, dates, or contract terms - An internal team member adding details visible to other recipients - An administrator collecting information separately from signatures Preparers are functionally equivalent to approvers (/docs/api/resources/recipients/approver). The difference is in the wording shown during the ceremony. Preparers see "Finish" as the final action. Approvers see "Approve". ## The preparer's ceremony The preparer accesses the envelope through the **preparer's ceremony**. The preparer reviews the documents and fills in all input places assigned to them. These places may include: - Text input fields for names, dates, or other values - Checkboxes for selecting options - Other data entry fields defined in the document Image: Text input (/docs/images/text-input-guides.png) After filling in all required places, the preparer clicks **Finish**. The envelope then proceeds to the next recipient. Image: Prepared confirmation (/docs/images/prepared-confirmation.png) Preparer actions are not recorded in the audit log. Only signer actions appear in the audit log attached to the deliverable. ## Workflow example ### Create an envelope Include a preparer recipient before any signers in the recipient list. ### Preparer completes their ceremony The preparer enters required information such as pricing, dates, or terms. ### Subsequent recipients see the data Recipients who act after the preparer see the document with the preparer's fields already filled in. ### Signers complete signing Signers review the document and add their signatures. ## Creating an envelope with a preparer Specify `"type": "preparer"` for recipients who should fill in fields before the signer receives the document. Use sequential routing so the preparer acts first. ```json // POST https://api.signatureapi.com/v1/envelopes // X-API-Key: key_test_... // Content-Type: application/json { "title": "Sales Agreement", "recipients": [ { "key": "sales_rep", "type": "preparer", "name": "Alex Smith", "email": "alex@company.com" }, { "key": "customer", "type": "signer", "name": "Jordan Lee", "email": "jordan@customer.com" } ], "routing": "sequential", //... } ``` In this example, the sales representative fills in the agreement details first. Then the customer receives the document to sign. With sequential routing, the preparer's input is visible to the signer. ## Assigning places to a preparer Assign places to a preparer using the `recipient_key` property. Preparers can fill in text inputs, checkboxes, and dropdowns. Signature and initials places cannot be assigned to preparers. ```json { "documents": [ { "places": [ { "type": "text_input", "recipient_key": "sales_rep", "key": "contract_value", //... }, { "type": "signature", "recipient_key": "customer", //... } ], //... } ], //... } ``` ## Delivery The `delivery_type` controls whether SignatureAPI emails the completed deliverable to the preparer. It defaults to `none`, so the preparer does not receive the deliverable. Set it to `email` if you want them to receive it. The preparer receives an email with the ceremony link when their ceremony uses `email_link` authentication, which is the default. To share the ceremony URL yourself instead, create the ceremony with `custom` authentication (/docs/api/guides/how-to/custom-authentication). ## Next steps - Recipient object (/docs/api/resources/recipients/object) - See all recipient properties - Recipient lifecycle (/docs/api/resources/recipients/lifecycle) - Understand recipient status transitions - Create a ceremony (/docs/api/resources/ceremonies/create) - Customize how the preparer accesses the envelope - Approver (/docs/api/resources/recipients/approver) - Add a reviewer who approves without signing - Envelope routing (/docs/api/resources/envelopes/routing) - Configure the order recipients act on the envelope ## Automatic Signer URL: https://signatureapi.com/docs/api/resources/recipients/automatic-signer Description: A recipient type whose signature is applied automatically by the system An **automatic signer** is a person whose signature is applied automatically by the system. The signer does not receive an email, does not access a ceremony, and does not interact with the document. You provide the signature and initials images when you create the envelope, along with a `mandate` recording why you are authorized to sign on their behalf. **Not equivalent across signature frameworks.** Because an automatic signer does not interact with the document, this recipient type does not produce the same legal weight as a standard signer in every jurisdiction. - **US (ESIGN Act, UETA).** Generally defensible when the initiator has recorded authority to sign on the person's behalf. The `mandate` field is designed to capture that authority basis on the audit log. - **EU (eIDAS).** SignatureAPI operates at the Simple Electronic Signature (SES) level for all recipient types. A standard signer's SES is strengthened by the signer's direct consent and signing action during the ceremony. An automatic signer has neither, so its evidentiary weight within SES is weaker and admissibility is decided case by case. Use a standard signer (/docs/api/resources/recipients/signer) when local regulation requires the signatory to interact with the document directly, or when the document warrants the stronger evidentiary trail that a live ceremony produces. Consult your legal counsel before using automatic signers for high-risk documents. Use an automatic signer when you have prior authorization to sign on the person's behalf and you want their signature to appear on the document without any live interaction. Common examples include: - A clinician's signature applied to prescriptions or reports under a standing authorization - A company officer's signature applied to routine documents under a power of attorney or corporate resolution - A notary or agent's signature applied under a recorded mandate ## Automatic signer vs. signer | | Automatic signer | Signer | |--|--|--| | Receives an invitation email | No | Yes (when the ceremony uses `email_link` authentication) | | Accesses a ceremony | No | Yes | | Consents to electronic signatures | No (authority is pre-declared) | Yes | | Adds signature during the envelope | No (provided at creation) | Yes | | Recorded in audit log | Yes | Yes | | Recipient type | `automatic_signer` | `signer` | An automatic signer counts as a signing recipient. An envelope that contains only automatic signers is valid and completes without any recipient interaction. ## How the signature is applied When you create an envelope that contains an automatic signer, SignatureAPI: 1. Validates the `signature` and `initials` you provide. Invalid uploads or missing images return a validation error. 2. Skips ceremony creation for the recipient. No email is sent. 3. Applies the provided images to every signature and initials place assigned to the recipient. 4. Transitions the recipient to `completed` and writes a single line to the audit log. The audit log line names the signer, cites the `mandate` verbatim, and attributes the authority to the initiator of the transaction: ``` Automatically signed by Dr. John Doe (#a3f9b2): With permission given and recorded on Jan 1 2026. As provided by the initiator of the electronic signature transaction. ``` ## Creating an envelope with an automatic signer Specify `"type": "automatic_signer"`, a `mandate`, and at least one of `signature` or `initials`. Supply `signature` if the recipient has any signature places, and `initials` if the recipient has any initials places. ```json // POST https://api.signatureapi.com/v1/envelopes // X-API-Key: key_test_... // Content-Type: application/json { "title": "Prescription", "recipients": [ { "key": "dr_doe", "type": "automatic_signer", "name": "Dr. John Doe", "signature": { "type": "drawn", "url": "https://api.signatureapi.com/v1/uploads/upl_1sAAaVfabdt0esVjmSTmLA" }, "initials": { "type": "drawn", "url": "https://api.signatureapi.com/v1/uploads/upl_2tBBbWgbcdeu1fsWknUnNB" }, "mandate": "With permission given and recorded on Jan 1 2026" } ], //... } ``` ### Required properties Must be `automatic_signer`. A unique identifier you assign to the recipient. Used to match the recipient with places and to identify them in events and webhook notifications. The full name of the signer. Appears in the audit log line that records the automatic signature. A short statement explaining why the initiator is authorized to sign on behalf of this person. This string is shown as-is in the audit log. Maximum 500 characters. Cannot be empty. Legal responsibility for the underlying authorization instrument (power of attorney, corporate resolution, standing authorization, or similar) sits with the initiator of the envelope. SignatureAPI records the `mandate` you supply verbatim in the audit log but does not verify its legal sufficiency. ### Conditional properties The recipient must be assigned at least one signing place (signature or initials), and the matching image must be supplied. The signature image to apply. Required when the recipient is assigned any place of type `signature`. A preset symbol object with `type` and `url`. ### Preset symbol The symbol type. Currently only `drawn` is supported. The URL of a PNG upload owned by your account. Both temporary uploads (from `POST /v1/uploads`) and permanent uploads stored via the Dashboard or `POST /v1/uploads/{id}/store` are accepted. The upload must not be expired. The initials image to apply. Required when the recipient is assigned any place of type `initials`. A preset symbol object with `type` and `url`. ### Preset symbol The symbol type. Currently only `drawn` is supported. The URL of a PNG upload owned by your account. Both temporary uploads (from `POST /v1/uploads`) and permanent uploads stored via the Dashboard or `POST /v1/uploads/{id}/store` are accepted. The upload must not be expired. ## Assigning places to an automatic signer Automatic signers must be assigned at least one `signature` or `initials` place. Assign places using the `recipient_key` property, the same as for signers. ```json { "documents": [ { "places": [ { "type": "signature", "recipient_key": "dr_doe", "key": "doctor_sig" }, { "type": "initials", "recipient_key": "dr_doe", "key": "doctor_init" } ], //... } ], //... } ``` If you assign a `signature` place, the `signature` image is required. If you assign an `initials` place, the `initials` image is required. Supplying a place without the matching image returns a missing preset symbol (/docs/v1/errors/missing-preset-symbol) error. ## Routing with an automatic signer Automatic signers follow the envelope's routing order. In a sequential envelope, an automatic signer earlier in the list completes first, and the next recipient activates. In a parallel envelope, the automatic signer completes as soon as the envelope is released, alongside any other parallel recipients. ```json { "routing": "sequential", "recipients": [ { "key": "doctor", "type": "automatic_signer", "name": "Dr. John Doe", "signature": { "type": "drawn", "url": "https://api.signatureapi.com/v1/uploads/upl_..." }, "mandate": "Standing authorization on file for prescription signatures" }, { "key": "patient", "type": "signer", "name": "Jordan Lee", "email": "jordan@example.com" } ] } ``` In this example, the doctor's signature is applied automatically, then the patient is invited to sign. ## Delivery Automatic signers have no email address and no `delivery_type`. They do not receive invitations and do not receive the completed deliverable. If you need a copy of the signed document delivered to the person whose signature was applied, handle that distribution in your application. ## Audit log The audit log records a single line for each automatic signer: ``` Automatically signed by {name} (#{recipient_hash}): {mandate}. As provided by the initiator of the electronic signature transaction. ``` The `recipient_hash` is the short identifier SignatureAPI assigns to the signer . The `mandate` value appears verbatim, so phrase it as a complete statement that stands on its own in the permanent record. ## Next steps - Recipient lifecycle (/docs/api/resources/recipients/lifecycle) - Understand recipient status transitions - Signer (/docs/api/resources/recipients/signer) - Add a recipient who signs interactively - Uploads (/docs/api/resources/uploads/object) - Create the PNG uploads referenced by `signature` and `initials` - Create an envelope (/docs/api/resources/envelopes/create) - Include automatic signers in a new envelope ## Get a recipient URL: https://signatureapi.com/docs/api/resources/recipients/get Description: Retrieves the details of an existing recipient. Retrieves the details of a recipient, including their current status, ceremony information, and completion timestamp. Use this endpoint to check a recipient's progress through the signing workflow. The response includes the full recipient object for the recipient's type (signer, approver, or preparer). ### Path Parameters The unique identifier of the recipient. Recipient IDs use the `re_` prefix. ### Returns Returns a `200 OK` status code along with a recipient object (/docs/api/resources/recipients/object) if successful, or an error (/docs/api/errors) otherwise. ```json // GET https://api.signatureapi.com/v1/recipients/{recipient_id} // X-API-Key: key_test_... ``` ```json // HTTP/1.1 200 OK { "id": "re_26w2VVV5JVm4j459TY5BNM", "envelope_id": "52872f0e-b919-4d69-89cd-e7e56af00548", "type": "signer", "key": "client", "name": "Emily Johnson", "email": "emily@example.com", "status": "completed", "status_updated_at": "2025-12-31T15:00:00.000Z", "completed_at": "2025-12-31T15:00:00.000Z", "delivery_type": "email", "signature_options": ["typed", "drawn"], "ceremony": { "authentication": [ { "type": "email_link", "subject_override": null, "message_override": null } ], "redirect_url": null, "redirect_delay": 3, "embeddable_in": [], "url_variant": "standard", "url": null }, "ceremony_creation": "automatic" } ``` ## Replace a recipient URL: https://signatureapi.com/docs/api/resources/recipients/replace Description: Replaces an existing recipient with a new one. Replaces a recipient with a new person. The original recipient's status changes to `replaced`, and a new recipient is created with the provided name and email. Use this endpoint when a recipient can no longer complete the envelope, for example after a hard bounce or if the wrong person was assigned. The new recipient inherits the original recipient's type, key, routing position, and assigned places. A new ceremony is created, and the invitation is sent if that ceremony uses `email_link` authentication. Recipients can only be replaced if they have not completed yet and the envelope status is `processing` or `in_progress`. ### Path Parameters The unique identifier of the recipient. Recipient IDs use the `re_` prefix. ### Body Parameters #### `name` (string, required) The full name of the recipient. Appears in invitation emails and is pre-filled for typed signatures. #### `email` (string, required) The email address of the recipient. SignatureAPI emails the ceremony link to this address when the ceremony uses `email_link` authentication, and the completed deliverable when `delivery_type` is `email`. ### Returns Returns a `201 Created` status code along with the new recipient object (/docs/api/resources/recipients/object) if successful, or an error (/docs/api/errors) otherwise. ```json // POST https://api.signatureapi.com/v1/recipients/{recipient_id}/replace // X-API-Key: key_test_... // Content-Type: application/json { "name": "Jane Doe", "email": "jane@example.com" } ``` ```json // HTTP/1.1 201 Created { "id": "re_8Unml6TyhNN8923Rminm40", "envelope_id": "52872f0e-b919-4d69-89cd-e7e56af00548", "type": "signer", "key": "client", "name": "Jane Doe", "email": "jane@example.com", "status": "pending", "status_updated_at": "2025-12-31T16:00:00.000Z", "completed_at": null, "delivery_type": "email", "signature_options": ["typed", "drawn"], "ceremony": { "authentication": [ { "type": "email_link", "subject_override": null, "message_override": null } ], "redirect_url": null, "redirect_delay": 3, "embeddable_in": [], "url_variant": "standard", "url": null }, "ceremony_creation": "automatic" } ``` ## Resend request URL: https://signatureapi.com/docs/api/resources/recipients/resend Description: Resends a signing request to the recipient. Resends the signing request to a recipient who has not yet completed their ceremony. Use this endpoint to: - **Send reminders.** If a recipient has not signed, resend the invitation as a reminder. - **Retry after a soft bounce.** If the invitation email was temporarily undeliverable, resend to try again. - **Re-deliver a lost email.** If a recipient reports not receiving the invitation, resend it. The resend is rate-limited to prevent email spam. The response includes `can_resend_at`, which tells you when the next resend can be initiated. The wait period increases with each attempt: | Attempts | Wait period | |----------|-------------| | 1-3 | 15 minutes | | 4-6 | 1 hour | | 7-10 | 24 hours | | Over 10 | No more resends allowed | The request can only be resent if the recipient's status is `sent` or `soft_bounced`, and the envelope status is `in_progress`. ### Path Parameters The unique identifier of the recipient. Recipient IDs use the `re_` prefix. ### Returns Returns a `200 OK` status code along with the following property: Time after which the next resend can be initiated, in ISO 8601 format. ```json // POST https://api.signatureapi.com/v1/recipients/{recipient_id}/resend // X-API-Key: key_test_... ``` ```json // HTTP/1.1 200 OK { "can_resend_at": "2025-12-31T22:00:00.000Z" } ``` ## Document URL: https://signatureapi.com/docs/api/resources/documents/object Description: The document object represents a PDF or DOCX file within an envelope A **document** is a PDF or DOCX file within an envelope (/docs/api/resources/envelopes/object). Each envelope can contain between 1 and 10 documents. Recipients sign, approve, or prepare documents during their ceremony (/docs/api/resources/ceremonies/object). Documents are defined inside the `documents` array when creating an envelope (/docs/api/resources/envelopes/create). They are not created or updated independently. A document belongs to an envelope (/docs/api/resources/envelopes/object). ## Document formats SignatureAPI supports two document formats. You must set the `format` property to match the file type. **PDF** (`format: "pdf"`) accepts standard PDF files. Place fields using placeholders (#place-positioning) embedded in the document text or fixed coordinates (#place-positioning) on a page. **DOCX** (`format: "docx"`) accepts Microsoft Word files. In addition to places, DOCX documents support template fields (/docs/api/resources/documents/templates) that merge dynamic data into the document before signing begins. If you upload a DOCX file but omit `format` or set it to `"pdf"`, the API returns a cannot-parse-document (/docs/v1/errors/cannot-parse-document) error. Always set `format: "docx"` for Word files. DOCX files created with Google Docs or LibreOffice may not be compatible. If you get a cannot-parse-document (/docs/v1/errors/cannot-parse-document) error, open the file in Microsoft Word and re-save it. This resolves most compatibility issues. ## Providing a file Set the `url` property to a publicly accessible URL for the file. SignatureAPI downloads the file when the envelope is created. You can host files on Amazon S3, Google Cloud Storage, Azure Blob Storage, Cloudflare R2, and other services. You can also upload files directly to SignatureAPI (/docs/api/resources/documents/url) and use the returned URL. ## Places Places (/docs/api/resources/places/object) are areas in a document where recipients interact or where information is displayed automatically. Input places include signatures, initials, text inputs, checkboxes, and dropdowns. Informational places include static text, completion dates, and recipient details. Define places in the `places` array. Each place has a `key` and a `type`. ## Place positioning A place must be positioned in the document. There are two methods. **Placeholders**: Embed `[[place_key]]` in the document text. The place appears at that location. This works for both PDF and DOCX documents. **Fixed positions**: Specify the `page`, `top`, and `left` values in the `fixed_positions` array. Coordinates are measured in points (1 point = 1/72 inch) from the top-left corner of the page. See Place Positioning (/docs/api/resources/places/positioning) for details and examples. ## Attributes ### PDF Document The unique identifier of the document. Document IDs start with `doc_`. The unique identifier of the envelope, in UUID format. A user-provided identifier for this document within the envelope. Must be unique within the envelope. Use the key to reference this document in other parts of the API. Only lowercase letters, numbers, and underscores are allowed. Must start with a letter. Maximum 32 characters. If not provided, a key is generated automatically. An optional display name for the document. When set, the title is shown to recipients during the signing ceremony and in deliverables. Defaults to `null` if not provided. Maximum 500 characters. The total number of pages in the document after processing. For DOCX templates, this reflects the page count after template data has been merged. The URL where the document or template file is located. The file must be publicly accessible. You can host files on Amazon S3, Google Cloud Storage, Azure Blob Storage, Cloudflare R2, and other services. You can also use the URL returned by the Create Upload (/docs/api/resources/uploads/create) endpoint. Learn more about your options in Document URL and Upload (/docs/api/resources/documents/url). The file format of the document. Determines which features are available. - `pdf`: Standard PDF file. Supports places via placeholders or fixed positions. - `docx`: Microsoft Word file. Supports template fields for dynamic content in addition to places. For PDF documents the format is `pdf`. ### fixed position The key of the place to position. Must match one of the `key` values in the document's `places` array. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The page number where the place is positioned. Page numbering starts at 1. The vertical distance from the top edge of the page to the bottom-left corner of the place, measured in points (1 point = 1/72 of an inch). For example, `360` places the field 5 inches from the top edge. The horizontal distance from the left edge of the page to the bottom-left corner of the place, measured in points (1 point = 1/72 of an inch). For example, `72` places the field 1 inch from the left edge. Areas within a document where a recipient provides input (such as a signature or text) or where a value is displayed automatically (such as a completion date). Each place has a `type` that determines its behavior. A place must be positioned using either a `[[place_key]]` placeholder in the document text or an entry in the `fixed_positions` array. Learn more about places (/docs/api/resources/places/object). ### signature place A location where the recipient, identified by `recipient_key`, draws or types their signature. A single recipient can have multiple signature places across different pages of a document. Specifies the type of place. For a signature place, the value must be `signature`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. The height of the signature place in points. The width is calculated automatically using a 5:2 ratio based on this height. Must be between 20 and 60. Defaults to 60. ### initials place A location where the recipient, identified by `recipient_key`, enters their initials. A single recipient can have multiple initials places across different pages of a document. Specifies the type of place. For an initials place, the value must be `initials`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. The height of the initials place in points. The width equals the height. Must be between 20 and 60. Defaults to 60. ### text place A read-only text value displayed at a specific location on the document. It is not interactive and does not require a recipient. Use this to pre-fill static information such as company names, reference numbers, or dates before the signing process begins. Specifies the type of place. For a text place, the value must be `text`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The text content to display on the document. This is a static value set when the envelope is created and cannot be changed by the recipient. Maximum length is 1000 characters. The font size in points. Must be between 1 and 144. The default is 12. The font color for this text place. Must be a six-digit hex color code with a leading `#`. Defaults to `#000000` (black). ### text input place A location where the recipient, identified by `recipient_key`, types free-form text. Supports input validation, placeholder text, and tooltip hints. Use `capture_as` to store the entered value in the envelope's captures. Specifies the type of place. For a text input place, the value must be `text_input`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. A key that stores the recipient's input in the envelope's `captures` object. When set, the value entered or selected by the recipient is saved under this key after the envelope is completed. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. Set to `null` to disable capture. A tooltip message displayed over the input text field during the signing ceremony. Learn more in Hints and Prompts (/docs/api/resources/places/text-input#hints-and-prompts). A placeholder message shown inside the input text field during the signing ceremony. Learn more in Hints and Prompts (/docs/api/resources/places/text-input#hints-and-prompts). Specifies whether the recipient must fill this field to complete the signing ceremony. Possible values are `required` or `optional`. The default is `required`. Defines the validation format for the user’s input. Accepted values: - `email` - `zipcode-us` - a custom regular expression, enclosed in `/`, for example: `/^[a-z0-9]{1,10}$/` Learn more in Format Validation (/docs/api/resources/places/text-input#format-validation). The message displayed when the user’s input does not match the required format. Learn more in Format Validation -> Adding a Custom Message (/docs/api/resources/places/text-input#adding-a-custom-message). The initial width of the text input field in points. The field may expand beyond this width during typing. Must be between 30 and 540. Defaults to 30. The font size in points. Must be between 6 and 12. Defaults to 12. ### boxed text input place A series of individual character boxes where the recipient, identified by `recipient_key`, enters text one character per box. Use this for structured data such as verification codes, ZIP codes, or the last four digits of an SSN. Use `capture_as` to store the entered value in the envelope's captures. Specifies the type of place. For a boxed text input place, the value must be `boxed_text_input`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. The number of individual character boxes to display. Must be between 1 and 100. Each box accepts a single character from the recipient. Specifies whether the recipient must fill all boxes to complete the signing ceremony. Possible values are `required` or `optional`. The default is `required`. A placeholder message shown inside the first box during the signing ceremony to guide the recipient. Learn more in Hints and Prompts (/docs/api/resources/places/boxed-text-input#hints-and-prompts). A tooltip message displayed over the boxed text input field during the signing ceremony. Learn more in Hints and Prompts (/docs/api/resources/places/boxed-text-input#hints-and-prompts). A key that stores the recipient's input in the envelope's `captures` object. When set, the value entered or selected by the recipient is saved under this key after the envelope is completed. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. Set to `null` to disable capture. The total width of the boxed input field in points. Must be between 30 and 540. The default is 30. The height of each individual box in points. The font size in points. Must be between 6 and 12. The default is 12. ### multiline text input place A location where the recipient, identified by `recipient_key`, enters text that spans multiple lines. Use this for comments, addresses, and longer descriptions. Use `capture_as` to store the entered value in the envelope's captures. Specifies the type of place. For a multi-line text input place, the value must be `multiline_text_input`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. Specifies whether the recipient must fill this field to complete the signing ceremony. Possible values are `required` or `optional`. The default is `required`. A placeholder message shown inside the input text field during the signing ceremony. Learn more in Hints and Prompts (/docs/api/resources/places/multiline-text-input#hints-and-prompts). A tooltip message displayed over the input text field during the signing ceremony. Learn more in Hints and Prompts (/docs/api/resources/places/multiline-text-input#hints-and-prompts). A key that stores the recipient's input in the envelope's `captures` object. When set, the value entered or selected by the recipient is saved under this key after the envelope is completed. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. Set to `null` to disable capture. The width of the multi-line text input place in points. Must be between 30 and 540. The default is 30. The number of lines for the multi-line text input field. Must be between 1 and 100. The line height in points. Must be greater than or equal to `font_size`. Must be between 6 and 72. The default is 12. The font size in points. Must be between 6 and 12. The default is 12. ### checkbox place A location where the recipient, identified by `recipient_key`, checks or unchecks a box. Use `capture_as` to store the checkbox value in the envelope's captures. Specifies the type of place. For a checkbox place, the value must be `checkbox`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. A key that stores the recipient's input in the envelope's `captures` object. When set, the value entered or selected by the recipient is saved under this key after the envelope is completed. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. Set to `null` to disable capture. The symbol to display in the checkbox when it is checked. Available options are `check` and `xmark`. The default is `check`. Specifies whether the recipient must check this box to complete the signing ceremony. Possible values are `required` or `optional`. The default is `optional`. The height of the checkbox in points. The width equals the height. Must be between 8 and 40. Defaults to 20. ### dropdown place A location where the recipient, identified by `recipient_key`, selects from a list of options. Options can be a custom list of label-value pairs or a predefined set such as country names or US state codes. Use `capture_as` to store the selected value in the envelope's captures. Specifies the type of place. For a dropdown place, the value must be `dropdown`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. The list of options available in the dropdown. Either an array of custom `label`/`value` pairs, or a string specifying a predefined option set such as `us_states_names` or `world_countries_names`. The pre-selected option when the dropdown is displayed. The display behavior of the dropdown. Possible values: `auto`, `select`, or `combobox`. Whether the recipient must select an option. Possible values: `required` or `optional`. A placeholder message shown inside the dropdown field during the signing ceremony. A tooltip message displayed when the user hovers over or focuses on the dropdown field. A key that stores the recipient's input in the envelope's `captures` object. When set, the value entered or selected by the recipient is saved under this key after the envelope is completed. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. Set to `null` to disable capture. The font size in points for the dropdown field. The width of the dropdown field in points. ### recipient completed date place Displays the date and time when the recipient, identified by `recipient_key`, completed their action on the envelope. Use `date_format` to control how the date is formatted. Specifies the type of place. For this kind of place, the value must be `recipient_completed_date`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. The date and time format using Moment.js syntax (https://momentjs.com/docs/#/displaying/format/). Common formats include `D MMM YYYY` (31 Dec 2025), `YYYY-MM-DD` (2025-12-31), and `MM/DD/YYYY` (12/31/2025). Defaults to `D MMM YYYY`. ### envelope completed date place Displays the date and time when the envelope was completed. The envelope completes when all recipients have finished their actions. Use `date_format` to control how the date is formatted. Specifies the type of place. For this kind of place, the value must be `envelope_completed_date`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The date and time format using Moment.js syntax (https://momentjs.com/docs/#/displaying/format/). Common formats include `D MMM YYYY` (31 Dec 2025), `YYYY-MM-DD` (2025-12-31), and `MM/DD/YYYY` (12/31/2025). Defaults to `D MMM YYYY`. ### recipient name place Displays the name of the recipient, identified by `recipient_key`, at a specific location on the document. The value is inserted automatically. This place is read-only and does not require any action from the recipient. Specifies the type of place. For this kind of place, the value must be `recipient_name`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. ### recipient email place Displays the email address of the recipient, identified by `recipient_key`, at a specific location on the document. The value is inserted automatically. This place is read-only and does not require any action from the recipient. Specifies the type of place. For this kind of place, the value must be `recipient_email`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. ### DOCX Document The unique identifier of the document. Document IDs start with `doc_`. The unique identifier of the envelope, in UUID format. A user-provided identifier for this document within the envelope. Must be unique within the envelope. Use the key to reference this document in other parts of the API. Only lowercase letters, numbers, and underscores are allowed. Must start with a letter. Maximum 32 characters. If not provided, a key is generated automatically. An optional display name for the document. When set, the title is shown to recipients during the signing ceremony and in deliverables. Defaults to `null` if not provided. Maximum 500 characters. The total number of pages in the document after processing. For DOCX templates, this reflects the page count after template data has been merged. The URL where the document or template file is located. The file must be publicly accessible. You can host files on Amazon S3, Google Cloud Storage, Azure Blob Storage, Cloudflare R2, and other services. You can also use the URL returned by the Create Upload (/docs/api/resources/uploads/create) endpoint. Learn more about your options in Document URL and Upload (/docs/api/resources/documents/url). The file format of the document. Determines which features are available. - `pdf`: Standard PDF file. Supports places via placeholders or fixed positions. - `docx`: Microsoft Word file. Supports template fields for dynamic content in addition to places. For DOCX documents the format is `docx`. Template data used to fill dynamic fields in a DOCX template. Each key corresponds to a `{{key}}` placeholder in the template file. Keys must be alphanumeric and at most 32 characters. Values can be strings, booleans, or nested objects. Nested keys map to dot-notation placeholders (for example, a key `person` with nested key `name` fills `{{person.name}}`). Defaults to `{}`. ### fixed position The key of the place to position. Must match one of the `key` values in the document's `places` array. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The page number where the place is positioned. Page numbering starts at 1. The vertical distance from the top edge of the page to the bottom-left corner of the place, measured in points (1 point = 1/72 of an inch). For example, `360` places the field 5 inches from the top edge. The horizontal distance from the left edge of the page to the bottom-left corner of the place, measured in points (1 point = 1/72 of an inch). For example, `72` places the field 1 inch from the left edge. Areas within a document where a recipient provides input (such as a signature or text) or where a value is displayed automatically (such as a completion date). Each place has a `type` that determines its behavior. A place must be positioned using either a `[[place_key]]` placeholder in the document text or an entry in the `fixed_positions` array. Learn more about places (/docs/api/resources/places/object). ### signature place A location where the recipient, identified by `recipient_key`, draws or types their signature. A single recipient can have multiple signature places across different pages of a document. Specifies the type of place. For a signature place, the value must be `signature`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. The height of the signature place in points. The width is calculated automatically using a 5:2 ratio based on this height. Must be between 20 and 60. Defaults to 60. ### initials place A location where the recipient, identified by `recipient_key`, enters their initials. A single recipient can have multiple initials places across different pages of a document. Specifies the type of place. For an initials place, the value must be `initials`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. The height of the initials place in points. The width equals the height. Must be between 20 and 60. Defaults to 60. ### text place A read-only text value displayed at a specific location on the document. It is not interactive and does not require a recipient. Use this to pre-fill static information such as company names, reference numbers, or dates before the signing process begins. Specifies the type of place. For a text place, the value must be `text`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The text content to display on the document. This is a static value set when the envelope is created and cannot be changed by the recipient. Maximum length is 1000 characters. The font size in points. Must be between 1 and 144. The default is 12. The font color for this text place. Must be a six-digit hex color code with a leading `#`. Defaults to `#000000` (black). ### text input place A location where the recipient, identified by `recipient_key`, types free-form text. Supports input validation, placeholder text, and tooltip hints. Use `capture_as` to store the entered value in the envelope's captures. Specifies the type of place. For a text input place, the value must be `text_input`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. A key that stores the recipient's input in the envelope's `captures` object. When set, the value entered or selected by the recipient is saved under this key after the envelope is completed. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. Set to `null` to disable capture. A tooltip message displayed over the input text field during the signing ceremony. Learn more in Hints and Prompts (/docs/api/resources/places/text-input#hints-and-prompts). A placeholder message shown inside the input text field during the signing ceremony. Learn more in Hints and Prompts (/docs/api/resources/places/text-input#hints-and-prompts). Specifies whether the recipient must fill this field to complete the signing ceremony. Possible values are `required` or `optional`. The default is `required`. Defines the validation format for the user’s input. Accepted values: - `email` - `zipcode-us` - a custom regular expression, enclosed in `/`, for example: `/^[a-z0-9]{1,10}$/` Learn more in Format Validation (/docs/api/resources/places/text-input#format-validation). The message displayed when the user’s input does not match the required format. Learn more in Format Validation -> Adding a Custom Message (/docs/api/resources/places/text-input#adding-a-custom-message). The initial width of the text input field in points. The field may expand beyond this width during typing. Must be between 30 and 540. Defaults to 30. The font size in points. Must be between 6 and 12. Defaults to 12. ### boxed text input place A series of individual character boxes where the recipient, identified by `recipient_key`, enters text one character per box. Use this for structured data such as verification codes, ZIP codes, or the last four digits of an SSN. Use `capture_as` to store the entered value in the envelope's captures. Specifies the type of place. For a boxed text input place, the value must be `boxed_text_input`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. The number of individual character boxes to display. Must be between 1 and 100. Each box accepts a single character from the recipient. Specifies whether the recipient must fill all boxes to complete the signing ceremony. Possible values are `required` or `optional`. The default is `required`. A placeholder message shown inside the first box during the signing ceremony to guide the recipient. Learn more in Hints and Prompts (/docs/api/resources/places/boxed-text-input#hints-and-prompts). A tooltip message displayed over the boxed text input field during the signing ceremony. Learn more in Hints and Prompts (/docs/api/resources/places/boxed-text-input#hints-and-prompts). A key that stores the recipient's input in the envelope's `captures` object. When set, the value entered or selected by the recipient is saved under this key after the envelope is completed. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. Set to `null` to disable capture. The total width of the boxed input field in points. Must be between 30 and 540. The default is 30. The height of each individual box in points. The font size in points. Must be between 6 and 12. The default is 12. ### multiline text input place A location where the recipient, identified by `recipient_key`, enters text that spans multiple lines. Use this for comments, addresses, and longer descriptions. Use `capture_as` to store the entered value in the envelope's captures. Specifies the type of place. For a multi-line text input place, the value must be `multiline_text_input`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. Specifies whether the recipient must fill this field to complete the signing ceremony. Possible values are `required` or `optional`. The default is `required`. A placeholder message shown inside the input text field during the signing ceremony. Learn more in Hints and Prompts (/docs/api/resources/places/multiline-text-input#hints-and-prompts). A tooltip message displayed over the input text field during the signing ceremony. Learn more in Hints and Prompts (/docs/api/resources/places/multiline-text-input#hints-and-prompts). A key that stores the recipient's input in the envelope's `captures` object. When set, the value entered or selected by the recipient is saved under this key after the envelope is completed. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. Set to `null` to disable capture. The width of the multi-line text input place in points. Must be between 30 and 540. The default is 30. The number of lines for the multi-line text input field. Must be between 1 and 100. The line height in points. Must be greater than or equal to `font_size`. Must be between 6 and 72. The default is 12. The font size in points. Must be between 6 and 12. The default is 12. ### checkbox place A location where the recipient, identified by `recipient_key`, checks or unchecks a box. Use `capture_as` to store the checkbox value in the envelope's captures. Specifies the type of place. For a checkbox place, the value must be `checkbox`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. A key that stores the recipient's input in the envelope's `captures` object. When set, the value entered or selected by the recipient is saved under this key after the envelope is completed. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. Set to `null` to disable capture. The symbol to display in the checkbox when it is checked. Available options are `check` and `xmark`. The default is `check`. Specifies whether the recipient must check this box to complete the signing ceremony. Possible values are `required` or `optional`. The default is `optional`. The height of the checkbox in points. The width equals the height. Must be between 8 and 40. Defaults to 20. ### dropdown place A location where the recipient, identified by `recipient_key`, selects from a list of options. Options can be a custom list of label-value pairs or a predefined set such as country names or US state codes. Use `capture_as` to store the selected value in the envelope's captures. Specifies the type of place. For a dropdown place, the value must be `dropdown`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. The list of options available in the dropdown. Either an array of custom `label`/`value` pairs, or a string specifying a predefined option set such as `us_states_names` or `world_countries_names`. The pre-selected option when the dropdown is displayed. The display behavior of the dropdown. Possible values: `auto`, `select`, or `combobox`. Whether the recipient must select an option. Possible values: `required` or `optional`. A placeholder message shown inside the dropdown field during the signing ceremony. A tooltip message displayed when the user hovers over or focuses on the dropdown field. A key that stores the recipient's input in the envelope's `captures` object. When set, the value entered or selected by the recipient is saved under this key after the envelope is completed. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. Set to `null` to disable capture. The font size in points for the dropdown field. The width of the dropdown field in points. ### recipient completed date place Displays the date and time when the recipient, identified by `recipient_key`, completed their action on the envelope. Use `date_format` to control how the date is formatted. Specifies the type of place. For this kind of place, the value must be `recipient_completed_date`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. The date and time format using Moment.js syntax (https://momentjs.com/docs/#/displaying/format/). Common formats include `D MMM YYYY` (31 Dec 2025), `YYYY-MM-DD` (2025-12-31), and `MM/DD/YYYY` (12/31/2025). Defaults to `D MMM YYYY`. ### envelope completed date place Displays the date and time when the envelope was completed. The envelope completes when all recipients have finished their actions. Use `date_format` to control how the date is formatted. Specifies the type of place. For this kind of place, the value must be `envelope_completed_date`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The date and time format using Moment.js syntax (https://momentjs.com/docs/#/displaying/format/). Common formats include `D MMM YYYY` (31 Dec 2025), `YYYY-MM-DD` (2025-12-31), and `MM/DD/YYYY` (12/31/2025). Defaults to `D MMM YYYY`. ### recipient name place Displays the name of the recipient, identified by `recipient_key`, at a specific location on the document. The value is inserted automatically. This place is read-only and does not require any action from the recipient. Specifies the type of place. For this kind of place, the value must be `recipient_name`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. ### recipient email place Displays the email address of the recipient, identified by `recipient_key`, at a specific location on the document. The value is inserted automatically. This place is read-only and does not require any action from the recipient. Specifies the type of place. For this kind of place, the value must be `recipient_email`. A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. ```json PDF Document { "id": "doc_3jBYlxa9gv0fGLzFAnfwxe", "envelope_id": "5e5ace5e-bd1e-4d5a-bb1f-6a2b2e42cd13", "key": "agreement", "title": "Service Agreement", "page_count": 3, "url": "https://pub-e5051420e98a4fdfb3fd42a62fbf06fa.r2.dev/agreement.pdf", "format": "pdf", "fixed_positions": [ { "place_key": "provider_signs_here", "page": 3, "top": 600, "left": 72 } ], "places": [ { "key": "provider_signs_here", "type": "signature", "recipient_key": "service_provider", "height": 60 }, { "key": "client_signs_here", "type": "signature", "recipient_key": "client", "height": 60 } ] } ``` ```json DOCX Document (Word Template) { "id": "doc_8hKpmnFR6CFr6oChasgVb9", "envelope_id": "5e5ace5e-bd1e-4d5a-bb1f-6a2b2e42cd13", "key": "agreement", "title": "Service Agreement", "page_count": 2, "url": "https://pub-e5051420e98a4fdfb3fd42a62fbf06fa.r2.dev/agreement-template.docx", "format": "docx", "data": { "date": "December 31st, 2025", "serviceProvider": { "name": "Jane Smith", "organization": "ACME Global, Inc." }, "client": { "name": "Michael J. Miller", "organization": "Miller Industries" } }, "fixed_positions": [], "places": [ { "key": "provider_signs_here", "type": "signature", "recipient_key": "service_provider", "height": 60 }, { "key": "client_signs_here", "type": "signature", "recipient_key": "client", "height": 60 } ] } ``` ## Document Templates URL: https://signatureapi.com/docs/api/resources/documents/templates Description: Generate documents from DOCX templates and dynamic data. SignatureAPI can generate a document from a static DOCX template combined with dynamic data you provide. Use this to create personalized documents without editing files manually before each send. To add signature fields or display dynamic values like a recipient's name, see Places (/docs/api/resources/places/object). ## How it works Create a DOCX file and embed **fields** and **conditionals** using double curly braces: `{{key}}`. When you create an envelope, provide the data in the `data` property of the document. SignatureAPI merges the template with your data and produces the final document. Provide the template URL in the `url` property and set `format` to `docx`. ```json // POST https://api.signatureapi.com/v1/envelopes // X-API-Key: key_test_... // Content-Type: application/json { "title": "Exploration Agreement", "documents": [ { "url": "https://www.example.com/agreement-template.docx", "format": "docx", "data": { "person": { "name": "Sherlock Holmes", "address": "221b Baker Street, London" }, "jurisdiction": "The United Kingdom", "mediation": false } } ], //... } ``` DOCX files created with software other than Microsoft Word (like Google Docs or LibreOffice) may not process correctly. If you get a cannot-parse-document (/docs/v1/errors/cannot-parse-document) error, open the file in Microsoft Word and save it again. Contact support if you don't have Microsoft Word. **`{{double curly braces}}` vs `[[double brackets]]`**: these serve different purposes: - `{{field_key}}`: **Template fields.** Inject dynamic content (names, dates, addresses) into the document text before signing. Only available in DOCX documents. - `[[place_key]]`: **Place placeholders.** Position signature fields, text inputs, checkboxes, and other interactive places. Works in both PDF and DOCX documents. See Place Positioning (/docs/api/resources/places/positioning). A DOCX document can use both: `{{}}` to inject content and `[[]]` to position places. ## Fields Fields mark locations in the template where data is inserted. Use double curly braces to define a field: `{{key}}`. **Template:** This agreement is entered into by \{\{name\}\}. **Data:** ```json { "name": "Sherlock Holmes" } ``` **Result:** This agreement is entered into by Sherlock Holmes. ### Nested objects Data values can be nested objects. Use dot notation in the template to reference nested keys. **Template:** This agreement is entered into by \{\{person.name\}\}, residing at \{\{person.address.houseNumber\}\} \{\{person.address.streetName\}\}, \{\{person.address.city\}\}. **Data:** ```json { "person": { "name": "Sherlock Holmes", "address": { "houseNumber": "221b", "streetName": "Baker Street", "city": "London" } } } ``` **Result:** This agreement is entered into by Sherlock Holmes, residing at 221b Baker Street, London. ## Conditionals Conditionals control which sections appear in the final document based on your data. **Name keys used in a condition with camelCase, not separators.** Inside `{{if ...}}`, an underscore in a nested key name causes a `template-error` (/docs/v1/errors/template-error). For example, `{{if person.is_signer}}` fails. Use camelCase or a single word instead: `{{if person.isSigner}}` or `{{if isSigner}}`. Underscores still work in regular fields like `{{person.is_signer}}` — only conditions are affected. ### If Use `{{if condition}}` and `{{endif}}` to show or hide a block of content. **Template:** Please read before proceeding. \{\{if showDisclaimer\}\} Information provided is for educational purposes only and should not be considered as professional advice. \{\{endif\}\} Use at your own discretion. With `"showDisclaimer": true`, the disclaimer appears. With `"showDisclaimer": false`, it is omitted. ### If-Else Use `{{if condition}}`, `{{else}}`, and `{{endif}}` to display one of two blocks based on a condition. **Template:** \{\{if mediation\}\} Any dispute shall be resolved by mediation, with each party bearing its own costs. \{\{else\}\} Any dispute shall be settled by arbitration, and the arbitrator's decision is final. \{\{endif\}\} With `"mediation": true`: Any dispute shall be resolved by mediation, with each party bearing its own costs. With `"mediation": false`: Any dispute shall be settled by arbitration, and the arbitrator's decision is final. ## Repeating regions If your data contains an array, you can mark a region of the document to be repeated once per item in that array. The simplest approach is to keep each repeating region in its own document. Most envelopes that need repeating content can be built this way without any extra template syntax. The advanced approach, range tags, is only needed when several repeating regions must live inside the same document. ### How a repeating region works A repeating region has two parts: 1. An **array** in the document's `data` payload. 2. A **region** in the DOCX template, marked with field tags that reference the items of that array. Field tags inside a repeating region use the array's name as part of the path, for example `{{events.name}}`. The engine detects the binding and duplicates the region once per item in the array. `events` here is just the JSON key you chose for your array. It is your name, not a reserved word. Replace it with whatever fits your data. ### A dynamic table Build a one row data table (header row plus a single data row) and place the field tags directly in the cells of the data row. **Template:** | Event | Date | Guests | |---|---|---| | `{{events.name}}` | `{{events.date}}` | `{{events.guests}}` | **Data:** ```json { "data": { "events": [ { "name": "Opening Reception", "date": "Mar 12", "guests": "120" }, { "name": "Closing Dinner", "date": "Mar 14", "guests": "80" } ] } } ``` **Result:** | Event | Date | Guests | |---|---|---| | Opening Reception | Mar 12 | 120 | | Closing Dinner | Mar 14 | 80 | The header row sits above the data row and is not repeated. The engine duplicates the data row once per item in the array. This works because the array `events` is referenced **only inside the data row** of one table. As soon as you reference the same array somewhere else in the document, the simple pattern breaks. To repeat content in more than one place, see the next sections. ### A repeating paragraph or bullet The same idea applies to a single paragraph or a single bullet (or numbered) list item. Place the field tags in the line you want to repeat. Do not wrap anything. **Template:** Schedule: \{\{events.name\}\} on \{\{events.date\}\}. End of schedule. **Data:** ```json { "data": { "events": [ { "name": "Opening Reception", "date": "Mar 12" }, { "name": "Closing Dinner", "date": "Mar 14" } ] } } ``` **Result:** Schedule: Opening Reception on Mar 12. Closing Dinner on Mar 14. End of schedule. The line containing the field tags is what gets duplicated. The lines before and after appear once. For a bullet item, write a single bullet with the field tags inside, and the engine produces one continuous list with one entry per item. ### Nested values inside a region Items in the array can be objects with nested fields. Use dot notation to reach them. **Template:** | Event | Hall | City | |---|---|---| | `{{events.name}}` | `{{events.venue.hall}}` | `{{events.venue.city}}` | **Data:** ```json { "data": { "events": [ { "name": "Opening Reception", "venue": { "hall": "Main Hall", "city": "London" } }, { "name": "Closing Dinner", "venue": { "hall": "Garden Tent", "city": "London" } } ] } } ``` **Result:** | Event | Hall | City | |---|---|---| | Opening Reception | Main Hall | London | | Closing Dinner | Garden Tent | London | The same dot notation works inside paragraphs and bullets. ### Combining several repeating regions When an envelope needs more than one repeating region, the recommended approach is to split the content across **multiple documents in the same envelope**. Each document has its own template and its own `data` payload, and each document can stay simple. ```json { "documents": [ { "url": "https://www.example.com/schedule.docx", "format": "docx", "data": { "events": [ ... ] } }, { "url": "https://www.example.com/signatories.docx", "format": "docx", "data": { "signatories": [ ... ] } } ] } ``` The recipient sees a single envelope. Internally, each document is processed with its own template and its own data. This avoids the extra template syntax described in the next section. ### Several repeating regions in one document If you really need more than one repeating region inside the **same** document, the simple pattern shown above is no longer enough. The engine has to be told where each region starts and ends, with two extra pieces of syntax: 1. A **root wrapper** around the entire document body. 2. A pair of **range tags** around each repeating region. ``` {{#data}} ...prose... {{#data.}} ...content to repeat... {{/data.}} ...more prose... {{#data.}} ...content to repeat... {{/data.}} {{/data}} ``` Inside the root wrapper, all field paths are fully qualified: `{{data..}}`. Only one root wrapper is supported per document. The placement of the range tags differs by region type: - **Paragraphs and bullets:** place the range tags on their own lines, immediately above and below the line you want to repeat. The tag lines do not appear in the output. - **Tables:** place `{{#data.}}` at the start of the **first cell** of the data row (before its field tag) and `{{/data.}}` at the end of the **last cell** of the same data row (after its field tag). The header row is not repeated; only the data row is. Do not place a table's range tags in paragraphs above and below the table. If you do, the entire table including the header is duplicated once per item. #### A combined example This template uses all three region types in one document. **Template:** \{\{#data\}\} **Schedule** | Event | Date | Guests | |---|---|---| | `{{#data.events}}{{data.events.name}}` | `{{data.events.date}}` | `{{data.events.guests}}{{/data.events}}` | **Signatories** \{\{#data.signatories\}\} - \{\{data.signatories.name\}\}, \{\{data.signatories.title\}\} \{\{/data.signatories\}\} **Notes** \{\{#data.notes\}\} Note: \{\{data.notes.text\}\} \{\{/data.notes\}\} \{\{/data\}\} **Data:** ```json { "data": { "events": [ { "name": "Kickoff", "date": "Mar 12", "guests": "120" }, { "name": "Workshop", "date": "Mar 13", "guests": "40" }, { "name": "Closing", "date": "Mar 14", "guests": "200" } ], "signatories": [ { "name": "Sherlock Holmes", "title": "Director" }, { "name": "John Watson", "title": "Co-Director" } ], "notes": [ { "text": "Bring ID." }, { "text": "Dress code is formal." } ] } } ``` **Result:** **Schedule** | Event | Date | Guests | |---|---|---| | Kickoff | Mar 12 | 120 | | Workshop | Mar 13 | 40 | | Closing | Mar 14 | 200 | **Signatories** - Sherlock Holmes, Director - John Watson, Co-Director **Notes** Note: Bring ID. Note: Dress code is formal. Each region iterates independently. The headings and surrounding text appear once. #### Why the wrapper is required Without the root wrapper and the range tags, the engine has to guess where each region starts and ends. With more than one array, or more than one binding to the same array, the guesses fail in characteristic ways: text gets dragged between regions, or the regions multiply against each other (three by three by three produces 27 copies of the innermost block, not 3). The DSWord engine docs note this directly: "When range tags are omitted, the template automatically calculates the start and end of a repeating block and may produce unwanted results." The wrapper plus range tags remove the guesswork. ### Pitfalls - **Prefer multiple documents over range tags.** Only reach for the root wrapper and range tags when a single document genuinely needs more than one repeating region. - **Pick one approach per template.** The simple pattern (no wrappers) and the range tag pattern (root wrapper plus range tags around each region) cannot be mixed in the same document. - **The simple pattern only works when the array is referenced once in the document.** As soon as you have a second binding to the same array, or a second array used elsewhere in the document, switch to range tags. - **Range tags around a table belong inside the cells of the data row,** not in paragraphs around the table. Otherwise the entire table is duplicated, header and all. - **Do not write literal `{{...}}` in non repeating prose**, even as documentation or examples. The engine attempts to evaluate it and fails with a `template-error` (/docs/v1/errors/template-error). To refer to a field name in body text, write it without the braces (for example, "the `events.name` field"). - **Every item in the array must include every field referenced inside the region.** A missing field produces a `cannot-populate-template` (/docs/v1/errors/cannot-populate-template) error. - **Field names are case sensitive.** `{{events.Name}}` and `{{events.name}}` are different paths. - **Place placeholders (`[[place_key]]`) do not belong inside a repeating region.** The region is duplicated and each copy would compete for the same place. Position signatures and other places outside the repeating region. ## Document URL and Upload URL: https://signatureapi.com/docs/api/resources/documents/url Description: Upload PDF or DOCX files via the dashboard, API, or external storage like S3 or Azure Every document in an envelope requires a `url` pointing to a PDF or DOCX file. SignatureAPI downloads the file when the envelope is created. There are three ways to provide a file URL: - Upload via the Dashboard (#upload-via-dashboard) - Upload via the API (#upload-via-api) - Host it externally (#external-store) on a service like S3 or Azure ## Upload via Dashboard Upload files to your account's **Library** in the Dashboard. Library files never expire and can be reused across multiple envelopes. This method works well for recurring documents and templates. To upload a file, go to the **Library** tab in the Dashboard. Image: (/docs/images/upload-library.png) Click **Upload a file** or drag and drop your file, then confirm the upload. Click **Copy URL** to copy the file URL. Use the URL in your document definition: ```json // POST https://api.signatureapi.com/v1/envelopes // X-API-Key: key_test_... // Content-Type: application/json { "title": "Service Agreement", "documents": [ { "url": "https://api.signatureapi.com/v1/uploads/upl_7kWstHtxXmje18omrlV6OA#agreement-v1", "format": "pdf" //... } ], "recipients": [ //... ] //... } ``` ## Upload via API Use the Create Upload (/docs/api/resources/uploads/create) endpoint to upload files programmatically. API uploads are temporary and intended for immediate use. To reuse a file, upload it to your Library in the Dashboard instead. The response from the Create Upload endpoint includes a `url` property. Use it as the document URL: ```json // POST https://api.signatureapi.com/v1/envelopes // X-API-Key: key_test_... // Content-Type: application/json { "title": "Service Agreement", "documents": [ { "url": "https://api.signatureapi.com/v1/uploads/upl_7kWstHtxXmje18omrlV6OA", "format": "pdf" //... } ], "recipients": [ //... ] //... } ``` ## External Store You can provide a publicly accessible URL from a supported hosting service. SignatureAPI downloads the file from the specified location. Supported hosting services: Use either pre-signed (recommended) or public URLs. Accepted formats: - `https://*.s3.*.amazonaws.com/*` - `https://*.s3.amazonaws.com/*` - `https://s3.amazonaws.com/*` - `https://s3.*.amazonaws.com/*` Use either signed (recommended) or public URLs. Accepted format: - `https://*.cloudfront.net/*` Use either pre-signed (recommended) or public URLs. Accepted formats: - `https://*.r2.dev/*` - `https://*.r2.cloudflarestorage.com/*` Use either pre-signed (recommended) or public URLs. Accepted format: - `https://*.blob.core.windows.net/*` Use either pre-signed (recommended) or public URLs. Accepted format: - `https://storage.googleapis.com/*` Ensure the file can be downloaded directly from the URL. Accepted format: - `https://*.public.blob.vercel-storage.com/*` Use either pre-signed (recommended) or public URLs. Accepted format: - `https://*.supabase.co/*` Ensure the file can be downloaded directly from the URL. Accepted format: - `https://drive.google.com/*` Ensure the file can be downloaded directly from the URL. Accepted format: - `https://www.dropbox.com/*` Ensure the file can be downloaded directly from the URL. Accepted format: - `https://*.convex.cloud/api/storage/*` Ensure the file can be downloaded directly from the URL. Accepted format: - `https://*.cdn.bubble.io/*` Want support for another source? Contact support (mailto:support@signatureapi.com). ## Place Object URL: https://signatureapi.com/docs/api/resources/places/object Description: Define signature fields, input areas, and auto-filled values at specific locations in documents A **place** is a location on a document where a recipient performs an action or where information is displayed automatically. Places define where signatures go, where recipients type text, and where dates or names are inserted. Places are defined in the `places` array on a document (/docs/api/resources/documents/object). Each element in the array represents one place within the document. The properties available on a place depend on its `type`. A place belongs to a document (/docs/api/resources/documents/object). To generate a document from a template with dynamic data before any recipient signs, use Document Templates (/docs/api/resources/documents/templates) instead. ## Place Types There are three categories of place: **signature** places for capturing signatures and initials, **interactive** places that require other input from a recipient, and **informational** places that insert values automatically. ### Signature places | Type | Description | |------|-------------| | `signature` (/docs/api/resources/places/signature) | The recipient draws or types their signature | | `initials` (/docs/api/resources/places/initials) | The recipient enters their initials | ### Interactive places Interactive places require sequential routing (/docs/api/resources/envelopes/routing). | Type | Description | |------|-------------| | `text_input` (/docs/api/resources/places/text-input) | The recipient types free-form text | | `boxed_text_input` (/docs/api/resources/places/boxed-text-input) | The recipient enters text into individual character boxes | | `multiline_text_input` (/docs/api/resources/places/multiline-text-input) | The recipient types text across multiple lines | | `dropdown` (/docs/api/resources/places/dropdown) | The recipient selects from a list of options | | `checkbox` (/docs/api/resources/places/checkbox) | The recipient checks or unchecks a box | | `radio_group` (/docs/api/resources/places/radio-group) | The recipient selects one option from a group of mutually exclusive options | ### Informational places | Type | Description | |------|-------------| | `text` (/docs/api/resources/places/text) | A static text value inserted on the document | | `recipient_completed_date` (/docs/api/resources/places/date#recipient-completed-date) | The date the recipient completed their action | | `envelope_completed_date` (/docs/api/resources/places/date#envelope-completed-date) | The date the envelope was completed by all recipients | | `recipient_name` (/docs/api/resources/places/recipient-name) | The recipient's name | | `recipient_email` (/docs/api/resources/places/recipient-email) | The recipient's email address | ## Positioning Every place must be positioned on the document. There are two ways to do this: - **Placeholder**: Embed `[[place_key]]` in the document text. The place appears where the placeholder is found. - **Fixed position**: Specify exact coordinates using page number, `top`, and `left` values measured in points (1 point = 1/72 inch). See Place Positioning (/docs/api/resources/places/positioning) for details. ```json Signature { "key": "employer_first_signature", "type": "signature", "recipient_key": "employer", "height": 60 } ``` ```json Initials { "key": "employer_initials", "type": "initials", "recipient_key": "employer", "height": 60 } ``` ```json Text input { "key": "buyer_email", "type": "text_input", "recipient_key": "buyer", "capture_as": "buyer_email", "prompt": "john@example.com", "hint": "Please enter your email", "format": "email", "requirement": "optional", "width": 200, "font_size": 8 } ``` ```json Boxed text input { "key": "verification_code", "type": "boxed_text_input", "recipient_key": "signer", "font_size": 12, "width": 150, "height": 20, "box_count": 6, "capture_as": "verification_code", "hint": "Enter the 6-digit code from your email", "requirement": "required" } ``` ```json Multiline text input { "key": "customer_comments", "type": "multiline_text_input", "recipient_key": "customer", "capture_as": "comments", "prompt": "Enter your comments here...", "hint": "Please provide detailed feedback", "requirement": "optional", "width": 400, "line_count": 5, "line_height": 14, "font_size": 10 } ``` ```json Dropdown { "key": "employment_type", "type": "dropdown", "recipient_key": "employee", "options": [ { "label": "Full-time", "value": "full_time" }, { "label": "Part-time", "value": "part_time" }, { "label": "Contract", "value": "contract" }, { "label": "Internship", "value": "internship" } ], "default": "Full-time", "capture_as": "employment_type", "prompt": "Select employment type", "hint": "Choose the type of employment", "requirement": "required", "width": 150, "font_size": 10 } ``` ```json Checkbox { "key": "receive_marketing_emails", "type": "checkbox", "recipient_key": "employee", "symbol": "check", "height": 10 } ``` ```json Radio group { "key": "billing_cycle", "type": "radio_group", "recipient_key": "customer", "options": [ { "value": "monthly" }, { "value": "annual" } ], "shape": "circle", "symbol": "fill", "default": "monthly", "capture_as": "billing_cycle", "requirement": "required", "height": 20 } ``` ```json Text { "key": "company_name", "type": "text", "value": "Lorem Ipsum Ltd", "font_size": 12, "font_color": "#000000" } ``` ```json Recipient completed date { "key": "employer_signed_at", "type": "recipient_completed_date", "recipient_key": "employer", "date_format": "YYYY-MM-DD" } ``` ```json Envelope completed date { "key": "signed_by_all_at", "type": "envelope_completed_date", "date_format": "MM/DD/YYYY HH:mm" } ``` ```json Recipient name { "key": "client_name", "type": "recipient_name", "recipient_key": "client" } ``` ```json Recipient email { "key": "client_email", "type": "recipient_email", "recipient_key": "client" } ``` ## Place Positioning URL: https://signatureapi.com/docs/api/resources/places/positioning Description: Position fields using text placeholders or fixed coordinates with page, x, and y values Every place must be positioned on a document. There are two methods: placeholders (#placeholders) embedded in the document text, or fixed positions (#fixed-positions) specified as coordinates. ### Placeholders A placeholder is a text string embedded directly in the document. Use the format `[[place_key]]`, where `place_key` matches the `key` of the corresponding place object. **`[[double brackets]]` vs `{{double curly braces}}`**: these serve different purposes: - `[[place_key]]`: **Place placeholders.** Position signature fields, text inputs, checkboxes, and other interactive places. Works in both PDF and DOCX documents. - `{{field_key}}`: **Template fields.** Inject dynamic content (names, dates, addresses) into the document text before signing. Only available in DOCX documents. See Document Templates (/docs/api/resources/documents/templates). A DOCX document can use both: `{{}}` to inject content and `[[]]` to position places. For example, to define placeholders for two places with the keys `licensor_signs_here` and `licensor_signed_at`: Image: Placeholder positioning (/docs/images/place-position-placeholder.webp) When the envelope is processed, each placeholder is replaced by the rendered place. If `licensor_signs_here` is a `signature` place, the recipient's signature appears over the placeholder. If `licensor_signed_at` is a `recipient_completed_date` place, the date appears there instead. Image: Placeholder positioning signed (/docs/images/place-position-placeholder-signed.webp) To hide placeholders from recipients, set the placeholder text color to white. Image: Placeholder positioning signed white text (/docs/images/place-position-placeholder-white.webp) ### Fixed Positions Fixed positions let you place a field at an exact location on a document page using coordinates. Specify the page number and the distances from the top (`top`) and left (`left`) edges of the page. Both `top` and `left` are measured in points (1 point = 1/72 inch) and can include decimal values. The coordinates reference the **bottom-left corner** of the place, as shown below. Image: Fixed place positioning (/docs/images/coordinates_fixed.webp) For example, to position a place with the key `employer_first_signature` at 1 inch from the left and 5 inches from the top of page 2: ```json "documents": [ { //... "fixed_positions": [ { "place_key": "employer_first_signature", "page": 2, "top": 360, "left": 72 } ] //... } ] ``` ## Attributes #### `place_key` (string) The key of the place to position. Must match the `key` of a place in the document's `places` array. #### `page` (number) The page number where the place is positioned. Page numbering starts at 1. #### `top` (number) The vertical distance from the top edge of the page to the bottom-left corner of the place, in points (1/72 inch). Decimal values are allowed. #### `left` (number) The horizontal distance from the left edge of the page to the bottom-left corner of the place, in points (1/72 inch). Decimal values are allowed. ## Legacy Signature Places Earlier versions of SignatureAPI used placeholders like `[[employee.signature]]`, which are called Legacy Signature Places (/docs/api/resources/places/signature-legacy). The current approach uses place objects with either placeholder or fixed position coordinates, as described above. Legacy signature places continue to work, and new projects should use the place objects approach. For Power Automate integration, legacy signature places are currently the only supported method. ## Captures URL: https://signatureapi.com/docs/api/resources/envelopes/captures Description: Retrieve data entered by recipients during signing ceremonies through the API Some place (/docs/api/resources/places/object) types allow recipients to enter data during the ceremony (/docs/api/resources/ceremonies/object), such as text input places (/docs/api/resources/places/text-input). The entered data is rendered in the signed document. Captures let you also access that data via the API. ## Defining captures Places that accept recipient input have a `capture_as` property. Set it to a key name to store the entered value on the envelope's `captures` object. Keys must be unique within the envelope. For example, this text input place asks a recipient to enter an 8-digit reference number: ```json // POST https://api.signatureapi.com/v1/envelopes // X-API-Key: key_test_... // Content-Type: application/json { "documents": [ { //... "places": [ { "key": "order_reference_number", "type": "text_input", "hint": "Your 8-digit reference code", "format": "/^[0-9]{8}$/", "recipient_key": "customer", "capture_as": "reference" } ] } ], "recipients": [ //... ], "title": "Order Confirmation" } ``` When the recipient completes the ceremony, the entered value is stored in the `captures` object on the envelope: ```json // HTTP/1.1 200 OK { "id": "55072f0e-b919-4d69-89cd-e7e56af00530", //... "captures": { "reference": "11223344" } } ``` ## More examples ```json Multiple text captures // Request places [ { "key": "ssn_last_four", "type": "text_input", "recipient_key": "applicant", "capture_as": "ssn_last_4", "format": "/^[0-9]{4}$/", "requirement": "required" }, { "key": "phone_number", "type": "text_input", "recipient_key": "applicant", "capture_as": "phone", "requirement": "required" } ] // Response captures { "captures": { "ssn_last_4": "1234", "phone": "555-123-4567" } } ``` ```json Checkbox capture // Request places [ { "key": "accept_terms", "type": "checkbox", "recipient_key": "customer", "capture_as": "terms_accepted", "requirement": "required" }, { "key": "marketing_opt_in", "type": "checkbox", "recipient_key": "customer", "capture_as": "marketing_consent" } ] // Response captures { "captures": { "terms_accepted": true, "marketing_consent": false } } ``` ```json Dropdown capture // Request places [ { "key": "state_selection", "type": "dropdown", "recipient_key": "applicant", "options": "us_states_2_letter_codes", "capture_as": "state", "requirement": "required" } ] // Response captures { "captures": { "state": "CA" } } ``` ## Signature Place URL: https://signatureapi.com/docs/api/resources/places/signature Description: Add signature fields to documents using fixed coordinates or text placeholders A **signature place** marks a specific location in a document where a recipient draws or types their signature. Each signature place is linked to one recipient through the `recipient_key`. A single recipient can have multiple signature places across different pages of a document. You can position signature places using either placeholders (/docs/api/resources/places/positioning/#placeholders) or fixed positions (/docs/api/resources/places/positioning/#fixed-positions). The width of a signature place is calculated automatically using a 5:2 ratio based on the `height`. ## Attributes #### `type` (enum, required) Specifies the type of place. For a signature place, the value must be `signature`. #### `key` (string, required) A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. #### `recipient_key` (string, required) The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. #### `height` (number) The height of the signature place in points. The width is calculated automatically using a 5:2 ratio based on this height. Must be between 20 and 60. Defaults to 60. ## Examples ```json Basic (Placeholder) "documents": [ { //... "places": [ { "key": "employer_first_signature", "type": "signature", "recipient_key": "employer", "height": 60 } ] //... } ] ``` ```json Fixed Position "documents": [ { //... "places": [ { "key": "employer_signature", "type": "signature", "recipient_key": "employer", "height": 60 } ], "fixed_positions": [ { "place_key": "employer_signature", "page": 2, "top": 360, "left": 72 } ] //... } ] ``` ```json Multiple Signatures (Same Recipient) "documents": [ { //... "places": [ { "key": "employer_signature_page_1", "type": "signature", "recipient_key": "employer", "height": 60 }, { "key": "employer_signature_page_3", "type": "signature", "recipient_key": "employer", "height": 60 } ] //... } ] ``` ```json Compact Signature "documents": [ { //... "places": [ { "key": "employee_signature", "type": "signature", "recipient_key": "employee", "height": 40 } ] //... } ] ``` ## Sizing guide The `height` property controls the signature field size in points. It must be between 20 and 60 (default: 60). The width is calculated automatically using a 5:2 ratio (width = height x 2.5). | Height | Width | Best for | |--------|-------|----------| | 20 | 50 | Tight layouts, small signature lines | | 40 | 100 | Compact documents with limited space | | 60 | 150 | Standard documents (default) | When using placeholders, the placeholder text (`[[place_key]]`) determines the position only. The rendered signature field uses the dimensions from the `height` property, not the size of the placeholder text. When using fixed positions, make sure the signature field fits within the page boundaries. A signature placed too close to the edge of a page may be clipped. ## Initials Place URL: https://signatureapi.com/docs/api/resources/places/initials Description: Add initials fields to documents for recipients to place their initials during signing An **initials place** marks a specific location in a document where a recipient enters their initials. Each initials place is linked to one recipient through the `recipient_key`. A single recipient can have multiple initials places across different pages. You can position initials places using either placeholders (/docs/api/resources/places/positioning/#placeholders) or fixed positions (/docs/api/resources/places/positioning/#fixed-positions). The width of an initials place equals its height (a square field). ## Attributes #### `type` (enum, required) Specifies the type of place. For an initials place, the value must be `initials`. #### `key` (string, required) A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. #### `recipient_key` (string, required) The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. #### `height` (number) The height of the initials place in points. The width equals the height. Must be between 20 and 60. Defaults to 60. ## Examples ```json Basic (Placeholder) "documents": [ { //... "places": [ { "key": "employer_initials", "type": "initials", "recipient_key": "employer", "height": 60 } ] //... } ] ``` ```json Fixed Position "documents": [ { //... "places": [ { "key": "employer_initials", "type": "initials", "recipient_key": "employer", "height": 40 } ], "fixed_positions": [ { "place_key": "employer_initials", "page": 1, "top": 720, "left": 500 } ] //... } ] ``` ```json Initials on Multiple Pages "documents": [ { //... "places": [ { "key": "client_initials_p1", "type": "initials", "recipient_key": "client", "height": 30 }, { "key": "client_initials_p2", "type": "initials", "recipient_key": "client", "height": 30 }, { "key": "client_initials_p3", "type": "initials", "recipient_key": "client", "height": 30 } ], "fixed_positions": [ { "place_key": "client_initials_p1", "page": 1, "top": 720, "left": 520 }, { "place_key": "client_initials_p2", "page": 2, "top": 720, "left": 520 }, { "place_key": "client_initials_p3", "page": 3, "top": 720, "left": 520 } ] //... } ] ``` ```json Compact Initials "documents": [ { //... "places": [ { "key": "witness_initials", "type": "initials", "recipient_key": "witness", "height": 25 } ] //... } ] ``` ## Text Input Place URL: https://signatureapi.com/docs/api/resources/places/text-input Description: Collect information from recipients during signing with text input fields A **text input place** marks a location in a document where a recipient types free-form text during the signing ceremony. These serve the same purpose as form fields in other e-signature platforms. Text input places are only available in envelopes with sequential signing. You can position text input places using either placeholders (/docs/api/resources/places/positioning/#placeholders) or fixed positions (/docs/api/resources/places/positioning/#fixed-positions). ## Hints and Prompts Use `hint` and `prompt` to guide recipients while they fill out a text field. - **`hint`**: A tooltip shown when the recipient hovers over or focuses on the field. - **`prompt`**: Placeholder text displayed inside the field. It disappears when the recipient starts typing. ```json { //... "hint": "Your 8-digit reference code", "prompt": "12345678" //... } ``` During the signing ceremony, the field appears like this: ## Format Validation The `format` property validates what the recipient can enter. You can use a predefined format or a custom regular expression. ### Predefined formats | Value | Description | |-------|-------------| | `email` | Email address | | `zipcode-us` | US ZIP code | More predefined formats are coming. Let us know (/support) if you need a specific format. ### Custom regular expressions Wrap a regular expression in forward slashes to define a custom format. For example, to require exactly 8 numeric digits: ```json { //... "format": "/^[0-9]{8}$/" //... } ``` ### Format messages Set `format_message` to show a custom message when the recipient's input does not match the required format. ```json { //... "format": "/^[0-9]{8}$/", "format_message": "Must be exactly 8 numeric digits (0-9)" //... } ``` During signing, the message is displayed like this: ## Capturing Input Set `capture_as` to store the value the recipient enters in the envelope's `captures` object. After the envelope is completed, you can retrieve the value using the key you specified. ## Size and Appearance - **`width`**: The initial width of the field in points (1/72 inch). The field may expand beyond this width as the recipient types. - **`font_size`**: The text size inside the field, in points. Must be between 6 and 12. Defaults to 12. ## Attributes #### `type` (enum, required) Specifies the type of place. For a text input place, the value must be `text_input`. #### `key` (string, required) A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. #### `recipient_key` (string, required) The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. #### `capture_as` (string) A key that stores the recipient's input in the envelope's `captures` object. When set, the value entered or selected by the recipient is saved under this key after the envelope is completed. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. Set to `null` to disable capture. #### `hint` (string) A tooltip message displayed over the input text field during the signing ceremony. Learn more in Hints and Prompts (/docs/api/resources/places/text-input#hints-and-prompts). #### `prompt` (string) A placeholder message shown inside the input text field during the signing ceremony. Learn more in Hints and Prompts (/docs/api/resources/places/text-input#hints-and-prompts). #### `requirement` (enum) Specifies whether the recipient must fill this field to complete the signing ceremony. Possible values are `required` or `optional`. The default is `required`. #### `format` (enum or regex) Defines the validation format for the user’s input. Accepted values: - `email` - `zipcode-us` - a custom regular expression, enclosed in `/`, for example: `/^[a-z0-9]{1,10}$/` Learn more in Format Validation (/docs/api/resources/places/text-input#format-validation). #### `format_message` (string) The message displayed when the user’s input does not match the required format. Learn more in Format Validation -> Adding a Custom Message (/docs/api/resources/places/text-input#adding-a-custom-message). #### `width` (number) The initial width of the text input field in points. The field may expand beyond this width during typing. Must be between 30 and 540. Defaults to 30. #### `font_size` (number) The font size in points. Must be between 6 and 12. Defaults to 12. ## Examples ```json Optional Email Field "documents": [ { //... "places": [ { "key": "buyer_email", "type": "text_input", "recipient_key": "buyer", "capture_as": "buyer_email", "prompt": "john@example.com", "hint": "Please enter your email", "format": "email", "requirement": "optional", "width": 200, "font_size": 8 } ] //... } ] ``` ```json Required Reference Number "documents": [ { //... "places": [ { "key": "reference_number", "type": "text_input", "recipient_key": "applicant", "capture_as": "ref_number", "prompt": "12345678", "hint": "Your 8-digit reference code", "format": "/^[0-9]{8}$/", "format_message": "Must be exactly 8 digits", "requirement": "required", "width": 120 } ] //... } ] ``` ```json Address Field (Wide) "documents": [ { //... "places": [ { "key": "mailing_address", "type": "text_input", "recipient_key": "borrower", "capture_as": "borrower_address", "prompt": "123 Main St, City, State ZIP", "hint": "Enter your full mailing address", "requirement": "required", "width": 350, "font_size": 10 } ] //... } ] ``` ```json US ZIP Code "documents": [ { //... "places": [ { "key": "zip_code", "type": "text_input", "recipient_key": "customer", "capture_as": "customer_zip", "prompt": "90210", "format": "zipcode-us", "requirement": "required", "width": 80 } ] //... } ] ``` ## Boxed Text Input Place URL: https://signatureapi.com/docs/api/resources/places/boxed-text-input Description: Collect structured data with individual character boxes for codes, SSN digits, or dates A **boxed text input place** displays a series of individual character boxes. Each box accepts one character, making this place type ideal for structured data such as verification codes, the last four digits of a Social Security Number, or date components. Image: Boxed Text Input (/docs/images/boxed-input.png) Boxed text input places are only available in envelopes with sequential signing. You can position boxed text input places using either placeholders (/docs/api/resources/places/positioning/#placeholders) or fixed positions (/docs/api/resources/places/positioning/#fixed-positions). ## Box Count The `box_count` property sets how many individual character boxes appear. Set this value based on the expected input length. | Use case | Recommended `box_count` | |----------|------------------------| | Verification code (6 digits) | 6 | | Last 4 of SSN | 4 | | ZIP code | 5 | | Year (YYYY) | 4 | | Month or day (MM/DD) | 2 | ## Hints and Prompts Use `hint` and `prompt` to guide recipients while filling in the boxes. - **`hint`**: A tooltip shown when the recipient hovers over or focuses on the field. - **`prompt`**: Placeholder text displayed inside the first box. ```json { //... "hint": "Enter the 6-digit code from your email", "prompt": "0" //... } ``` ## Capturing Input Set `capture_as` to store the entered value in the envelope's `captures` object. After the envelope is completed, retrieve the value using the key you specified. ## Size and Appearance - **`width`**: The total width of the field in points (1/72 inch). Must be between 30 and 540. Defaults to 30. - **`height`**: The height of each box in points (1/72 inch). Must be between 6 and 60. - **`font_size`**: The text size inside each box, in points. Must be between 6 and 12. Defaults to 12. ## Attributes #### `type` (enum, required) Specifies the type of place. For a boxed text input place, the value must be `boxed_text_input`. #### `key` (string, required) A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. #### `recipient_key` (string, required) The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. #### `box_count` (number) The number of individual character boxes to display. Must be between 1 and 100. Each box accepts a single character from the recipient. #### `capture_as` (string) A key that stores the recipient's input in the envelope's `captures` object. When set, the value entered or selected by the recipient is saved under this key after the envelope is completed. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. Set to `null` to disable capture. #### `hint` (string) A tooltip message displayed over the boxed text input field during the signing ceremony. Learn more in Hints and Prompts (/docs/api/resources/places/boxed-text-input#hints-and-prompts). #### `prompt` (string) A placeholder message shown inside the first box during the signing ceremony to guide the recipient. Learn more in Hints and Prompts (/docs/api/resources/places/boxed-text-input#hints-and-prompts). #### `requirement` (enum) Specifies whether the recipient must fill all boxes to complete the signing ceremony. Possible values are `required` or `optional`. The default is `required`. #### `width` (number, required) The total width of the boxed input field in points. Must be between 30 and 540. The default is 30. #### `height` (number, required) The height of each individual box in points. #### `font_size` (number, required) The font size in points. Must be between 6 and 12. The default is 12. ## Examples ```json Verification Code "documents": [ { //... "places": [ { "key": "verification_code", "type": "boxed_text_input", "recipient_key": "signer", "font_size": 12, "width": 150, "height": 20, "box_count": 6, "capture_as": "verification_code", "hint": "Enter the 6-digit code from your email", "requirement": "required" } ] //... } ] ``` ```json Last 4 of SSN "documents": [ { //... "places": [ { "key": "ssn_last_four", "type": "boxed_text_input", "recipient_key": "applicant", "font_size": 12, "width": 100, "height": 20, "box_count": 4, "capture_as": "ssn_last_four", "hint": "Last 4 digits of your Social Security Number", "requirement": "required" } ] //... } ] ``` ```json Tax ID (EIN) "documents": [ { //... "places": [ { "key": "ein", "type": "boxed_text_input", "recipient_key": "taxpayer", "font_size": 12, "width": 225, "height": 20, "box_count": 9, "capture_as": "ein", "hint": "Enter your 9-digit Employer Identification Number", "requirement": "required" } ] //... } ] ``` ## Multi-Line Text Input Place URL: https://signatureapi.com/docs/api/resources/places/multiline-text-input Description: Collect longer text from recipients during signing with multi-line input fields A **multi-line text input place** marks a location in a document where a recipient enters text that spans multiple lines. Unlike text input places (/docs/api/resources/places/text-input), which are single-line fields, multi-line text input places support multiple lines of text. Use them for comments, addresses, descriptions, or any input that may span several lines. Multi-line text input places are only available in envelopes with sequential signing. You can position multi-line text input places using either placeholders (/docs/api/resources/places/positioning/#placeholders) or fixed positions (/docs/api/resources/places/positioning/#fixed-positions). ## Hints and Prompts Use `hint` and `prompt` to guide recipients while they fill out the field. - **`hint`**: A tooltip shown when the recipient hovers over or focuses on the field. - **`prompt`**: Placeholder text displayed inside the field. It disappears when the recipient starts typing. ```json { //... "hint": "Describe the reason for this request", "prompt": "Enter your comments here..." //... } ``` ## Capturing Input Set `capture_as` to store the entered value in the envelope's `captures` object. After the envelope is completed, retrieve the value using the key you specified. ## Size and Appearance - **`width`**: The width of the field in points (1/72 inch). Must be between 30 and 540. - **`line_count`**: The number of visible lines. Required. Must be between 1 and 100. - **`line_height`**: The vertical spacing between lines in points. Must be between 6 and 72. Must be greater than or equal to `font_size`. Defaults to 12. - **`font_size`**: The text size inside the field, in points. Must be between 6 and 12. Defaults to 12. ## Attributes #### `type` (enum, required) Specifies the type of place. For a multi-line text input place, the value must be `multiline_text_input`. #### `key` (string, required) A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. #### `recipient_key` (string, required) The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. #### `capture_as` (string) A key that stores the recipient's input in the envelope's `captures` object. When set, the value entered or selected by the recipient is saved under this key after the envelope is completed. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. Set to `null` to disable capture. #### `hint` (string) A tooltip message displayed over the input text field during the signing ceremony. Learn more in Hints and Prompts (/docs/api/resources/places/multiline-text-input#hints-and-prompts). #### `prompt` (string) A placeholder message shown inside the input text field during the signing ceremony. Learn more in Hints and Prompts (/docs/api/resources/places/multiline-text-input#hints-and-prompts). #### `requirement` (enum) Specifies whether the recipient must fill this field to complete the signing ceremony. Possible values are `required` or `optional`. The default is `required`. #### `width` (number, required) The width of the multi-line text input place in points. Must be between 30 and 540. The default is 30. #### `line_count` (integer, required) The number of lines for the multi-line text input field. Must be between 1 and 100. #### `line_height` (number) The line height in points. Must be greater than or equal to `font_size`. Must be between 6 and 72. The default is 12. #### `font_size` (number) The font size in points. Must be between 6 and 12. The default is 12. ## Examples ```json Comments Field "documents": [ { //... "places": [ { "key": "customer_comments", "type": "multiline_text_input", "recipient_key": "customer", "capture_as": "comments", "prompt": "Enter your comments here...", "hint": "Please provide detailed feedback", "requirement": "optional", "width": 400, "line_count": 5, "line_height": 14, "font_size": 10 } ] //... } ] ``` ```json Mailing Address "documents": [ { //... "places": [ { "key": "full_address", "type": "multiline_text_input", "recipient_key": "applicant", "capture_as": "mailing_address", "prompt": "Enter your complete mailing address", "requirement": "required", "width": 350, "line_count": 3 } ] //... } ] ``` ```json Reason for Request "documents": [ { //... "places": [ { "key": "request_reason", "type": "multiline_text_input", "recipient_key": "requester", "capture_as": "reason", "hint": "Describe why this request is needed", "requirement": "required", "width": 450, "line_count": 4, "font_size": 10 } ] //... } ] ``` ## Dropdown Place URL: https://signatureapi.com/docs/api/resources/places/dropdown Description: Add dropdown selection fields with predefined options for recipients to choose from A **dropdown place** marks a location in a document where a recipient selects one option from a predefined list during the signing ceremony. Image: Dropdown (/docs/images/dropdown.png) Dropdown places are only available in envelopes with sequential signing. You can position dropdown places using either placeholders (/docs/api/resources/places/positioning/#placeholders) or fixed positions (/docs/api/resources/places/positioning/#fixed-positions). ## Options The `options` property defines the choices available in the dropdown. You can provide either custom options or a predefined option set. ### Custom options Supply an array of objects. Each object requires a `label` (displayed to the recipient) and accepts an optional `value` (stored when the option is selected). If `value` is omitted, `label` is used as the stored value. ```json { //... "options": [ { "label": "Full-time", "value": "full_time" }, { "label": "Part-time", "value": "part_time" }, { "label": "Contract", "value": "contract" } ] //... } ``` ### Predefined option sets For common selections like countries or US states, use a predefined option set by specifying one of these string values: | Value | Description | Example values | |-------|-------------|----------------| | `world_countries_names` | Full country names | "United States", "Canada", "Germany" | | `world_countries_2_letter_codes` | ISO 3166-1 alpha-2 codes | "US", "CA", "DE" | | `world_countries_3_letter_codes` | ISO 3166-1 alpha-3 codes | "USA", "CAN", "DEU" | | `world_countries_numeric_codes` | ISO 3166-1 numeric codes | "840", "124", "276" | | `us_states_names` | Full US state names | "California", "Texas", "New York" | | `us_states_2_letter_codes` | US state abbreviations | "CA", "TX", "NY" | ```json { //... "options": "world_countries_names" //... } ``` ## Default Selection Use the `default` property to pre-select an option when the dropdown is displayed. The value is matched first against the `label` of each option, then against the `value`. If no match is found, a validation error is returned. ```json { //... "options": "us_states_names", "default": "California" //... } ``` ## Behavior The `behavior` property controls how the dropdown is rendered during the signing ceremony. | Behavior | Description | |----------|-------------| | `auto` (default) | Renders as a standard dropdown for 10 or fewer options, and as a searchable combobox for more than 10 options. | | `select` | Always renders as a standard dropdown list. | | `combobox` | Always renders as a searchable dropdown with type-ahead filtering. | For large option sets like country lists, the `auto` behavior uses `combobox` since there are more than 10 options. ```json { //... "options": "world_countries_names", "behavior": "combobox" //... } ``` ## Hints and Prompts Use `hint` and `prompt` to guide recipients while making their selection. - **`hint`**: A tooltip shown when the recipient hovers over or focuses on the dropdown. - **`prompt`**: Placeholder text shown inside the dropdown before a selection is made. ```json { //... "hint": "Select your country of residence", "prompt": "Choose a country..." //... } ``` ## Capturing Input Set `capture_as` to store the selected value in the envelope's `captures` object. After the envelope is completed, retrieve the value using the key you specified. ## Size and Appearance - **`width`**: The width of the dropdown field in points (1/72 inch). Must be between 30 and 540. Defaults to 30. - **`font_size`**: The text size inside the dropdown, in points. Must be between 6 and 12. Defaults to 12. ## Attributes #### `type` (enum, required) Specifies the type of place. For a dropdown place, the value must be `dropdown`. #### `key` (string, required) A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. #### `recipient_key` (string, required) The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. #### `options` (array or enum, required) Specifies the list of options available in the dropdown. You can provide either **custom options** or a **predefined option set**. **Custom options**: An array of objects, each with a `label` (displayed to the user) and an optional `value` (captured when selected). If `value` is omitted, the `label` is used as the value. ```json "options": [ { "label": "Option A", "value": "a" }, { "label": "Option B", "value": "b" } ] ``` **Predefined options**: A string specifying a built-in option set: | Value | Description | |-------|-------------| | `world_countries_names` | Country names (e.g., "United States", "Canada") | | `world_countries_2_letter_codes` | ISO 3166-1 alpha-2 codes (e.g., "US", "CA") | | `world_countries_3_letter_codes` | ISO 3166-1 alpha-3 codes (e.g., "USA", "CAN") | | `world_countries_numeric_codes` | ISO 3166-1 numeric codes (e.g., "840", "124") | | `us_states_names` | US state names (e.g., "California", "Texas") | | `us_states_2_letter_codes` | US state codes (e.g., "CA", "TX") | #### `default` (string) Specifies the option that is pre-selected when the dropdown is displayed. The value is first matched against the `label` of each option. If no match is found, it is matched against the `value` of each option. If no match is found, a validation error is returned. #### `behavior` (enum) Specifies the behavior of the dropdown during the signing ceremony. Possible values: - `auto` (default): Automatically selects the best behavior based on the number of options. Uses `select` for 10 or fewer options, and `combobox` for more than 10 options. - `select`: Displays a standard dropdown list. Best for short lists where users can quickly scan all options. - `combobox`: Displays a searchable dropdown with type-ahead filtering. Best for long lists where users need to search for their selection. #### `requirement` (enum) Specifies whether the recipient must select an option to complete the signing ceremony. Possible values are `required` or `optional`. The default is `required`. #### `prompt` (string) A placeholder message shown inside the dropdown field during the signing ceremony. Maximum length is 100 characters. Learn more in Hints and Prompts (/docs/api/resources/places/dropdown#hints-and-prompts). #### `hint` (string) A tooltip message displayed when the user hovers over or focuses on the dropdown field during the signing ceremony. Maximum length is 100 characters. Learn more in Hints and Prompts (/docs/api/resources/places/dropdown#hints-and-prompts). #### `capture_as` (string) A key that stores the recipient's input in the envelope's `captures` object. When set, the value entered or selected by the recipient is saved under this key after the envelope is completed. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. Set to `null` to disable capture. #### `font_size` (number) The font size in points. Must be between 6 and 12. The default is 12. #### `width` (number) The width of the dropdown field in points. Must be between 30 and 540. The default is 30. ## Examples ```json Custom Options "documents": [ { //... "places": [ { "key": "employment_type", "type": "dropdown", "recipient_key": "employee", "options": [ { "label": "Full-time", "value": "full_time" }, { "label": "Part-time", "value": "part_time" }, { "label": "Contract", "value": "contract" }, { "label": "Internship", "value": "internship" } ], "default": "Full-time", "capture_as": "employment_type", "prompt": "Select employment type", "hint": "Choose the type of employment", "requirement": "required", "width": 150, "font_size": 10 } ] //... } ] ``` ```json Country Selection "documents": [ { //... "places": [ { "key": "country_of_residence", "type": "dropdown", "recipient_key": "applicant", "options": "world_countries_names", "default": "United States", "behavior": "combobox", "capture_as": "country", "prompt": "Select your country", "hint": "Choose your country of residence", "requirement": "required", "width": 200, "font_size": 10 } ] //... } ] ``` ```json US State Selection "documents": [ { //... "places": [ { "key": "state_selection", "type": "dropdown", "recipient_key": "customer", "options": "us_states_2_letter_codes", "capture_as": "state", "prompt": "Select state", "requirement": "required", "width": 80, "font_size": 10 } ] //... } ] ``` ## Checkbox Place URL: https://signatureapi.com/docs/api/resources/places/checkbox Description: Add checkbox fields to documents for recipients to check during signing ceremonies A **checkbox place** marks a specific location in a document where a recipient checks or unchecks a box during the signing ceremony. Checkbox places are only available in envelopes with sequential signing. You can position checkbox places using either placeholders (/docs/api/resources/places/positioning/#placeholders) or fixed positions (/docs/api/resources/places/positioning/#fixed-positions). ## Symbol The `symbol` property controls what mark is shown when the box is checked. Use `check` for a checkmark (default) or `xmark` for an X. ## Requirement Set `requirement` to `required` to force the recipient to check the box before completing their action. Set it to `optional` to allow the recipient to skip it. ## Capturing Input Set `capture_as` to store whether the box was checked in the envelope's `captures` object. After the envelope is completed, retrieve the value using the key you specified. ## Size The `height` property sets the height of the checkbox in points (1/72 inch). The width equals the height. Must be between 8 and 40. Defaults to 20. ## Attributes #### `type` (enum, required) Specifies the type of place. For a checkbox place, the value must be `checkbox`. #### `key` (string, required) A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. #### `recipient_key` (string, required) The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. #### `capture_as` (string) A key that stores the recipient's input in the envelope's `captures` object. When set, the value entered or selected by the recipient is saved under this key after the envelope is completed. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. Set to `null` to disable capture. #### `symbol` (enum) The symbol to display in the checkbox when it is checked. Available options are `check` and `xmark`. The default is `check`. #### `requirement` (enum) Specifies whether the recipient must check this box to complete the signing ceremony. Possible values are `required` or `optional`. The default is `optional`. #### `height` (number) The height of the checkbox in points. The width equals the height. Must be between 8 and 40. Defaults to 20. ## Examples ```json Basic (Optional) "documents": [ { //... "places": [ { "key": "receive_marketing_emails", "type": "checkbox", "recipient_key": "employee", "symbol": "check", "height": 10 } ] //... } ] ``` ```json Required Checkbox "documents": [ { //... "places": [ { "key": "accept_terms", "type": "checkbox", "recipient_key": "customer", "symbol": "check", "requirement": "required", "height": 12 } ] //... } ] ``` ```json X Symbol "documents": [ { //... "places": [ { "key": "decline_arbitration", "type": "checkbox", "recipient_key": "customer", "symbol": "xmark", "height": 10 } ] //... } ] ``` ```json With Capture "documents": [ { //... "places": [ { "key": "agreed_to_terms", "type": "checkbox", "recipient_key": "borrower", "symbol": "check", "requirement": "required", "capture_as": "terms_accepted", "height": 12 } ] //... } ] ``` ## Radio Group Place URL: https://signatureapi.com/docs/api/resources/places/radio-group Description: Add single-choice questions where recipients select exactly one option from a group A **radio group place** marks the options of a single-choice question in a document. The recipient selects exactly one option from the group during the signing ceremony. Radio group places are only available in envelopes with sequential signing. Unlike a dropdown, each option is a separate mark placed independently on the document. Options that belong to the same group are mutually exclusive: selecting one clears the others. ## Options The `options` property lists the choices in the group. Each option carries a `value`, which is the value captured when the recipient selects that option. ```json { //... "key": "billing_cycle", "options": [ { "value": "monthly" }, { "value": "annual" } ] //... } ``` An option `value` must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. ## Positioning You position each option individually, not the group as a whole. Address an option with a `group_key:value` key, where `group_key` is the `key` of the radio group place. A `billing_cycle` group with options `monthly` and `annual` gives you two keys to position: - `billing_cycle:monthly` - `billing_cycle:annual` Use those keys as placeholders (/docs/api/resources/places/positioning/#placeholders) in the document: ```text [[billing_cycle:monthly]] Monthly [[billing_cycle:annual]] Annual ``` Or as fixed positions (/docs/api/resources/places/positioning/#fixed-positions): ```json { //... "fixed_positions": [ { "place_key": "billing_cycle:monthly", "page": 1, "top": 300, "left": 40 }, { "place_key": "billing_cycle:annual", "page": 1, "top": 340, "left": 40 } ] //... } ``` This lets you spread the options of one question across the document, wherever they appear in your layout. ## Shape and Symbol Two properties control how the control is drawn. `shape` sets the geometry. Use `circle` for a round radio button (default), or `square` for a box that matches documents printing square options. `symbol` sets the mark drawn on the selected option. Use `fill` for a solid mark (default), `check` for a checkmark, or `xmark` for an X. A `fill` symbol takes the shape of the control. ```json { //... "shape": "square", "symbol": "check" //... } ``` ## Default Selection Use `default` to preselect an option when the place is displayed. Its value must match the `value` of one of the options in the group. If no match is found, a validation error is returned. ```json { //... "options": [{ "value": "monthly" }, { "value": "annual" }], "default": "monthly" //... } ``` ## Requirement Set `requirement` to `required` to force the recipient to select an option before completing their action. This is the default. Set it to `optional` to let the recipient skip the question. An optional group can also be cleared after the fact: the recipient clicks the selected option again to return the group to no selection. ## Capturing Input Set `capture_as` to store the selected option in the envelope's `captures` object. The captured value is the `value` of the option the recipient chose, not the group key. For a `billing_cycle` group captured as `billing_cycle`, a recipient who selects the `annual` option produces: ```json { //... "captures": { "billing_cycle": "annual" } //... } ``` ## Size The `height` property sets the height of each option in points (1/72 inch). The width equals the height. Must be between 8 and 40. Defaults to 20. ## Attributes #### `type` (enum, required) Specifies the type of place. For a radio group place, the value must be `radio_group`. #### `key` (string, required) A unique identifier for this group within the document. Combined with an option `value`, it forms the `group_key:value` key used to position each option. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. #### `recipient_key` (string, required) The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. #### `options` (array, required) The set of allowed options in the group. Each option is an object with a `value`, which is captured when the recipient selects that option. ```json "options": [ { "value": "monthly" }, { "value": "annual" } ] ``` A `value` must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. Position each option with its `group_key:value` key. Learn more in Positioning (/docs/api/resources/places/radio-group#positioning). #### `shape` (enum) The geometry of the control. Available options are `circle` and `square`. The default is `circle`. #### `symbol` (enum) The symbol drawn when an option in the group is selected. A `fill` symbol takes the shape of the control. Available options are `fill`, `check`, and `xmark`. The default is `fill`. #### `requirement` (enum) Specifies whether the recipient must select an option to complete the signing ceremony. Possible values are `required` or `optional`. The default is `required`. #### `default` (string) The option selected by default when the place is displayed. Must match the `value` of one of the options in the group. If no match is found, a validation error is returned. Set to `null` for no preselection. #### `capture_as` (string) A key that stores the selected option in the envelope's `captures` object. The captured value is the `value` of the option the recipient chose. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. Set to `null` to disable capture. #### `height` (number) The height of each option in points. The width equals the height. Must be between 8 and 40. The default is 20. ## Examples ```json Billing Cycle "documents": [ { //... "places": [ { "key": "billing_cycle", "type": "radio_group", "recipient_key": "customer", "options": [ { "value": "monthly" }, { "value": "annual" } ], "default": "monthly", "capture_as": "billing_cycle", "requirement": "required" } ], "fixed_positions": [ { "place_key": "billing_cycle:monthly", "page": 1, "top": 300, "left": 40 }, { "place_key": "billing_cycle:annual", "page": 1, "top": 340, "left": 40 } ] //... } ] ``` ```json Square Checkboxes "documents": [ { //... "places": [ { "key": "delivery", "type": "radio_group", "recipient_key": "customer", "options": [ { "value": "email" }, { "value": "post" } ], "shape": "square", "symbol": "check", "capture_as": "delivery", "requirement": "required", "height": 14 } ] //... } ] ``` ```json Optional Question "documents": [ { //... "places": [ { "key": "newsletter", "type": "radio_group", "recipient_key": "customer", "options": [ { "value": "yes" }, { "value": "no" } ], "capture_as": "newsletter", "requirement": "optional" } ] //... } ] ``` ## Text Place URL: https://signatureapi.com/docs/api/resources/places/text Description: Insert static text strings at specific locations in documents before signing A **text place** inserts a static, read-only text value at a specific location in a document. It does not require any action from a recipient. The value is set when the envelope is created and cannot be changed by recipients. Text places are useful for pre-filling information such as company names, reference numbers, or contract dates before the signing process begins. Use text places with fixed positions to fill in PDF form fields before the first recipient signs. You can position text places using either placeholders (/docs/api/resources/places/positioning/#placeholders) or fixed positions (/docs/api/resources/places/positioning/#fixed-positions). ## Attributes #### `type` (enum, required) Specifies the type of place. For a text place, the value must be `text`. #### `key` (string, required) A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. #### `value` (string, required) The text content to display on the document. This is a static value set when the envelope is created and cannot be changed by the recipient. Maximum length is 1000 characters. #### `font_size` (number) The font size in points. Must be between 1 and 144. The default is 12. #### `font_color` (string) The font color for this text place. Must be a six-digit hex color code with a leading `#`. Defaults to `#000000` (black). ## Examples ```json Basic Text "documents": [ { //... "places": [ { "key": "company_name", "type": "text", "value": "Lorem Ipsum Ltd", "font_size": 12, "font_color": "#000000" } ] //... } ] ``` ```json Pre-fill Date "documents": [ { //... "places": [ { "key": "agreement_date", "type": "text", "value": "January 27, 2026", "font_size": 11 } ] //... } ] ``` ```json Large Header Text "documents": [ { //... "places": [ { "key": "document_title", "type": "text", "value": "LOAN AGREEMENT", "font_size": 18, "font_color": "#000000" } ] //... } ] ``` ```json Colored Text "documents": [ { //... "places": [ { "key": "account_number", "type": "text", "value": "ACC-2026-00142", "font_size": 10, "font_color": "#0066cc" } ] //... } ] ``` ```json Fixed Position (PDF Form Fill) "documents": [ { //... "places": [ { "key": "customer_id", "type": "text", "value": "CUST-88421", "font_size": 10 } ], "fixed_positions": [ { "place_key": "customer_id", "page": 1, "top": 145, "left": 200 } ] //... } ] ``` ## Date Places URL: https://signatureapi.com/docs/api/resources/places/date Description: Automatically insert completion dates for individual recipients or the entire envelope Date places insert completion timestamps automatically at a specific location in a document. There are two types: one that records when a specific recipient (#recipient-completed-date) completed their action, and one that records when the entire envelope (#envelope-completed-date) was completed. You can position date places using either placeholders (/docs/api/resources/places/positioning/#placeholders) or fixed positions (/docs/api/resources/places/positioning/#fixed-positions). ## Date Format Both date place types accept a `date_format` property that controls how the date is rendered. Use Moment.js format syntax (https://momentjs.com/docs/#/displaying/format/). The default format is `D MMM YYYY`, which renders as _31 Dec 2025_. Common formats: | Format string | Example output | |---------------|----------------| | `D MMM YYYY` | 31 Dec 2025 | | `YYYY-MM-DD` | 2025-12-31 | | `MM/DD/YYYY` | 12/31/2025 | | `MMMM D, YYYY` | December 31, 2025 | | `DD/MM/YYYY HH:mm` | 31/12/2025 14:30 | --- ## Recipient Completed Date A **recipient completed date** place records the date and time when the specific recipient identified by `recipient_key` completed their action on the envelope. ### Example ```json "documents": [ { //... "places": [ { "key": "employer_signed_at", "type": "recipient_completed_date", "recipient_key": "employer", "date_format": "YYYY-MM-DD" } ] //... } ] ``` ### Attributes #### `type` (enum, required) Specifies the type of place. For this kind of place, the value must be `recipient_completed_date`. #### `key` (string, required) A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. #### `recipient_key` (string, required) The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. #### `date_format` (string) The date and time format using Moment.js syntax (https://momentjs.com/docs/#/displaying/format/). Common formats include `D MMM YYYY` (31 Dec 2025), `YYYY-MM-DD` (2025-12-31), and `MM/DD/YYYY` (12/31/2025). Defaults to `D MMM YYYY`. #### `font_size` (number) The font size in points. Must be between 1 and 144. Defaults to 12. --- ## Envelope Completed Date An **envelope completed date** place records the date and time when the entire envelope was completed, meaning all recipients have finished their actions. This place type does not require a `recipient_key` because it applies to the envelope as a whole. ### Example ```json "documents": [ { //... "places": [ { "key": "signed_by_all_at", "type": "envelope_completed_date", "date_format": "MM/DD/YYYY HH:mm" } ] //... } ] ``` ### Attributes #### `type` (enum, required) Specifies the type of place. For this kind of place, the value must be `envelope_completed_date`. #### `key` (string, required) A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. #### `date_format` (string) The date and time format using Moment.js syntax (https://momentjs.com/docs/#/displaying/format/). Common formats include `D MMM YYYY` (31 Dec 2025), `YYYY-MM-DD` (2025-12-31), and `MM/DD/YYYY` (12/31/2025). Defaults to `D MMM YYYY`. #### `font_size` (number) The font size in points. Must be between 1 and 144. Defaults to 12. --- ## More Examples ```json ISO Format (YYYY-MM-DD) "documents": [ { //... "places": [ { "key": "signed_date", "type": "recipient_completed_date", "recipient_key": "signer", "date_format": "YYYY-MM-DD" } ] //... } ] ``` ```json US Format (MM/DD/YYYY) "documents": [ { //... "places": [ { "key": "completion_date", "type": "recipient_completed_date", "recipient_key": "client", "date_format": "MM/DD/YYYY" } ] //... } ] ``` ```json With Time (DD/MM/YYYY HH:mm) "documents": [ { //... "places": [ { "key": "timestamp", "type": "envelope_completed_date", "date_format": "DD/MM/YYYY HH:mm" } ] //... } ] ``` ```json Long Format "documents": [ { //... "places": [ { "key": "signed_on", "type": "recipient_completed_date", "recipient_key": "witness", "date_format": "MMMM D, YYYY" } ] //... } ] ``` ## Recipient Name Place URL: https://signatureapi.com/docs/api/resources/places/recipient-name Description: Automatically insert the recipient's name at a specific location in the document A **recipient name place** inserts the name of the recipient identified by `recipient_key` at a specific location in the document. The value is inserted automatically and does not require any action from the recipient. You can position recipient name places using either placeholders (/docs/api/resources/places/positioning/#placeholders) or fixed positions (/docs/api/resources/places/positioning/#fixed-positions). ## Font Size Use `font_size` to control the size of the inserted text in points (1/72 inch). Must be between 1 and 144. Defaults to 12. ## Attributes #### `type` (enum, required) Specifies the type of place. For this kind of place, the value must be `recipient_name`. #### `key` (string, required) A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. #### `recipient_key` (string, required) The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. #### `font_size` (number) The font size in points. Must be between 1 and 144. Defaults to 12. ## Examples ```json Basic (Placeholder) "documents": [ { //... "places": [ { "key": "client_name", "type": "recipient_name", "recipient_key": "client" } ] //... } ] ``` ```json Fixed Position "documents": [ { //... "places": [ { "key": "signer_name", "type": "recipient_name", "recipient_key": "signer" } ], "fixed_positions": [ { "place_key": "signer_name", "page": 1, "top": 180, "left": 150 } ] //... } ] ``` ```json Multiple Recipients "documents": [ { //... "places": [ { "key": "buyer_name", "type": "recipient_name", "recipient_key": "buyer" }, { "key": "seller_name", "type": "recipient_name", "recipient_key": "seller" } ] //... } ] ``` ```json Custom Font Size "documents": [ { //... "places": [ { "key": "employee_name", "type": "recipient_name", "recipient_key": "employee", "font_size": 10 } ] //... } ] ``` ## Recipient Email Place URL: https://signatureapi.com/docs/api/resources/places/recipient-email Description: Automatically insert the recipient's email address at a specific location in the document A **recipient email place** inserts the email address of the recipient identified by `recipient_key` at a specific location in the document. The value is inserted automatically and does not require any action from the recipient. You can position recipient email places using either placeholders (/docs/api/resources/places/positioning/#placeholders) or fixed positions (/docs/api/resources/places/positioning/#fixed-positions). ## Font Size Use `font_size` to control the size of the inserted text in points (1/72 inch). Must be between 1 and 144. Defaults to 12. ## Attributes #### `type` (enum, required) Specifies the type of place. For this kind of place, the value must be `recipient_email`. #### `key` (string, required) A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. #### `recipient_key` (string, required) The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array. #### `font_size` (number) The font size in points. Must be between 1 and 144. Defaults to 12. ## Examples ```json Basic (Placeholder) "documents": [ { //... "places": [ { "key": "client_email", "type": "recipient_email", "recipient_key": "client" } ] //... } ] ``` ```json Fixed Position "documents": [ { //... "places": [ { "key": "signer_email", "type": "recipient_email", "recipient_key": "signer" } ], "fixed_positions": [ { "place_key": "signer_email", "page": 1, "top": 200, "left": 150 } ] //... } ] ``` ```json Multiple Recipients "documents": [ { //... "places": [ { "key": "buyer_email", "type": "recipient_email", "recipient_key": "buyer" }, { "key": "seller_email", "type": "recipient_email", "recipient_key": "seller" } ] //... } ] ``` ```json Custom Font Size "documents": [ { //... "places": [ { "key": "applicant_email", "type": "recipient_email", "recipient_key": "applicant", "font_size": 10 } ] //... } ] ``` ## Deliverable URL: https://signatureapi.com/docs/api/resources/deliverables/object Description: The deliverable object represents the final signed PDF generated when an envelope is completed. A deliverable is the final PDF generated when all recipients complete an envelope. It contains the signed documents and, depending on the type, an audit log with a certificate of completion. SignatureAPI automatically creates a deliverable when an envelope completes. You can also create additional deliverables manually using the Create Deliverable (/docs/api/resources/deliverables/create) endpoint. A deliverable belongs to an envelope (/docs/api/resources/envelopes/object). ## Types SignatureAPI offers two deliverable types: | Type | Description | |------|-------------| | Standard deliverable (/docs/api/resources/deliverables/standard) | Includes the signed documents and an audit log. This is the default. | | Simple deliverable (/docs/api/resources/deliverables/simple) | Includes the signed documents only, without an audit log. | ## Lifecycle A deliverable's `status` tracks its progress from creation to completion. See the deliverable lifecycle (/docs/api/resources/deliverables/lifecycle) for details on each status. ## Attributes ### Standard Deliverable The standard deliverable includes an audit log. To get signed documents without an audit log, use the simple deliverable (/docs/api/resources/deliverables/simple) instead. The unique identifier for this deliverable. A user-provided name for this deliverable. Use this to identify deliverables when an envelope has more than one. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Between 1 and 32 characters. The unique identifier of the envelope, in UUID format. The type of the deliverable. - `standard`: Includes the signed documents and an audit log with a certificate of completion. This is the default. - `simple`: Includes the signed documents only, without an audit log. For standard deliverables, the type is `standard`. The current status of the deliverable. - `pending`: The envelope is not yet completed. The deliverable is waiting to be generated. - `processing`: The envelope has completed and the deliverable is being generated. This usually takes a few seconds. - `generated`: The deliverable is ready. The `url` property contains a download link. - `failed`: The deliverable failed to generate. This is rare. SignatureAPI support is notified automatically. The URL for downloading the deliverable. `null` until the deliverable reaches `generated` status. By default, this is a pre-signed URL. It requires no additional authentication and expires after 1 hour. If the link has expired, retrieve the deliverable again to get a fresh URL. If your account uses authenticated URLs (for HIPAA compliance, for example), access this URL with your API key as you would any other API request. Authenticated URLs do not expire. The language for system-generated text in the audit log, including labels and the certificate of completion. Does not affect the content of the signed documents. Supported values: `en` (English), `es` (Spanish), `fr` (French), `it` (Italian), `pt` (Portuguese), `de` (German), `zh` (Chinese Simplified), `hu` (Hungarian). Defaults to the envelope language. The timezone used for timestamps in the audit log. Must be a valid IANA Time Zone Database identifier (e.g., `America/New_York`, `Europe/London`). Does not affect timestamps inside the signed documents. Defaults to the envelope timezone. The format for timestamps in the audit log. Uses MomentJS format tokens (e.g., `MM/DD/YYYY HH:mm:ss`). Does not affect timestamps inside the signed documents. Defaults to the envelope timestamp format. The keys of the documents to include in the deliverable. By default, all documents in the envelope are included. Use this to create a deliverable with only a subset of documents. For example, generate separate deliverables for different recipients. Accepts between 1 and 10 document keys. The password used to encrypt the deliverable. Recipients must enter this password to access the downloaded file. Password requirements: - Between 4 and 32 characters - Letters and numbers only (no special characters or spaces) When returned in API responses, the password value is masked for security (displayed as `********`). Password protection is available upon request. Contact support (/support) to enable this feature. The time the deliverable was created, in ISO 8601 format. Set when the envelope is created, or when a deliverable is created via the API. The time the deliverable was successfully generated, in ISO 8601 format. `null` until the deliverable reaches `generated` status. ### Simple Deliverable The simple deliverable does not include an audit log. To get signed documents with an audit log, use the standard deliverable (/docs/api/resources/deliverables/standard) instead. The unique identifier for this deliverable. A user-provided name for this deliverable. Use this to identify deliverables when an envelope has more than one. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Between 1 and 32 characters. The unique identifier of the envelope, in UUID format. The type of the deliverable. - `standard`: Includes the signed documents and an audit log with a certificate of completion. This is the default. - `simple`: Includes the signed documents only, without an audit log. For simple deliverables, the type is `simple`. The current status of the deliverable. - `pending`: The envelope is not yet completed. The deliverable is waiting to be generated. - `processing`: The envelope has completed and the deliverable is being generated. This usually takes a few seconds. - `generated`: The deliverable is ready. The `url` property contains a download link. - `failed`: The deliverable failed to generate. This is rare. SignatureAPI support is notified automatically. The URL for downloading the deliverable. `null` until the deliverable reaches `generated` status. By default, this is a pre-signed URL. It requires no additional authentication and expires after 1 hour. If the link has expired, retrieve the deliverable again to get a fresh URL. If your account uses authenticated URLs (for HIPAA compliance, for example), access this URL with your API key as you would any other API request. Authenticated URLs do not expire. The keys of the documents to include in the deliverable. By default, all documents in the envelope are included. Use this to create a deliverable with only a subset of documents. For example, generate separate deliverables for different recipients. Accepts between 1 and 10 document keys. The password used to encrypt the deliverable. Recipients must enter this password to access the downloaded file. Password requirements: - Between 4 and 32 characters - Letters and numbers only (no special characters or spaces) When returned in API responses, the password value is masked for security (displayed as `********`). Password protection is available upon request. Contact support (/support) to enable this feature. The time the deliverable was created, in ISO 8601 format. Set when the envelope is created, or when a deliverable is created via the API. The time the deliverable was successfully generated, in ISO 8601 format. `null` until the deliverable reaches `generated` status. ```json Standard { "id": "del_LXRDwyTeJDVrWXmjwxsAGPq", "name": null, "envelope_id": "52872f0e-b919-4d69-89cd-e7e56af00548", "type": "standard", "status": "generated", "url": "https://vault.signatureapi.com/envelopes/52872f0e-b919-4d69-89cd-e7e56af00548/deliverables/del_LXRDwyTeJDVrWXmjwxsAGPq...", "language": "en", "timezone": "America/New_York", "timestamp_format": "MM/DD/YYYY HH:mm:ss", "included_documents": ["contract", "addendum"], "password": null, "created_at": "2024-01-01T00:00:00Z", "generated_at": "2024-01-01T00:01:00Z" } ``` ```json Simple { "id": "del_MYSExzUfKEWsXYnkywsAGQr", "name": null, "envelope_id": "52872f0e-b919-4d69-89cd-e7e56af00548", "type": "simple", "status": "generated", "url": "https://vault.signatureapi.com/envelopes/52872f0e-b919-4d69-89cd-e7e56af00548/deliverables/del_MYSExzUfKEWsXYnkywsAGQr...", "included_documents": ["contract", "addendum"], "password": null, "created_at": "2024-01-01T00:00:00Z", "generated_at": "2024-01-01T00:01:00Z" } ``` ## Deliverable Lifecycle URL: https://signatureapi.com/docs/api/resources/deliverables/lifecycle Description: The lifecycle and statuses of a deliverable. A deliverable moves through the following statuses: | Status | Description | |--------|-------------| | `pending` | The envelope is not yet completed. The deliverable is waiting to be generated. | | `processing` | The envelope has completed and the deliverable is being generated. This usually takes a few seconds. | | `generated` | The deliverable is ready. The `url` property contains a download link. | | `failed` | The deliverable failed to generate. This is rare. SignatureAPI support is notified automatically. | Subscribe to the `deliverable.generated` (/docs/api/resources/events/deliverable-events#deliverable-generated) webhook event to be notified when a deliverable is ready for download. ## Standard Deliverable URL: https://signatureapi.com/docs/api/resources/deliverables/standard Description: Generate a signed PDF that includes the signed documents and a detailed audit log of the signing process. The standard deliverable is a PDF that contains both the signed documents and an audit log. The audit log records every action taken during the signing process and includes a certificate of completion. This is the default deliverable type. SignatureAPI deliverables are tamper-proof and secured with a cryptographic seal that verifies their authenticity (/docs/api/resources/deliverables/verification). ## Example ### Standard Deliverable Example -> Link: /docs/api/resources/deliverables/standard-deliverable.pdf Download an example of a standard deliverable. ## Generating a Standard Deliverable You can generate a standard deliverable in two ways: automatically when the envelope completes, or manually using the Create Deliverable endpoint. ### Automatic (On Envelope Completion) By default, SignatureAPI automatically generates a standard deliverable when an envelope completes. The deliverable is sent to recipients when it is ready. The deliverable inherits the envelope's `language`, `timezone`, and `timestamp_format` settings. You can override these by including a `deliverable` object when creating the envelope. For example, to set the deliverable's audit log language to English while the envelope uses French: ```json // POST https://api.signatureapi.com/v1/envelopes // X-API-Key: key_test_... // Content-Type: application/json { "title": "Service Agreement", "language": "fr", "documents": [ //... ], "recipients": [ //... ], "deliverable": { "type": "standard", "language": "en" } } ``` ### Manual (Create Deliverable Endpoint) You can also create a standard deliverable manually at any time after the envelope completes, using the Create Deliverable (/docs/api/resources/deliverables/create) endpoint. ```json // POST https://api.signatureapi.com/v1/envelopes/{envelope_id}/deliverables // X-API-Key: key_test_... // Content-Type: application/json { "type": "standard" } ``` ## Customization ### Language The `language` property sets the language for system-generated text in the audit log, such as labels and the certificate of completion. It does not affect the content of the signed documents. See available languages (/docs/api/resources/envelopes/language). Defaults to the envelope language. ### Timezone The `timezone` property sets the timezone for timestamps in the audit log. It does not affect timestamps inside the signed documents. See available timezones (/docs/api/resources/envelopes/timezone). Defaults to the envelope timezone. ### Timestamp Format The `timestamp_format` property sets the format for timestamps in the audit log. It does not affect timestamps inside the signed documents. See available timestamp formats (/docs/api/resources/envelopes/timestamp-format). Defaults to the envelope timestamp format. ### Included Documents The `included_documents` property specifies which documents from the envelope to include in the deliverable. By default, all documents are included. Accepts between 1 and 10 document keys. Use this to generate separate deliverables for different documents, or to exclude certain documents from the final PDF. ```json { "type": "standard", "included_documents": ["contract", "addendum"] } ``` ## Password Protection To protect your deliverable with password encryption, see Password Protection (/docs/api/resources/deliverables/password). ## Simple Deliverable URL: https://signatureapi.com/docs/api/resources/deliverables/simple Description: Generate a signed PDF that includes only the signed documents, without an audit log. The simple deliverable is a PDF that contains only the signed documents. No audit log pages are included in the output. The audit log is still embedded as metadata within the PDF for verification purposes. Use a simple deliverable when you want a clean document without the audit log visible in the PDF pages. If you need the audit log included in the PDF, use the standard deliverable (/docs/api/resources/deliverables/standard) instead. SignatureAPI deliverables are tamper-proof and secured with a cryptographic seal that verifies their authenticity (/docs/api/resources/deliverables/verification). ## Example ### Simple Deliverable Example -> Link: /docs/api/resources/deliverables/simple-deliverable.pdf Download an example of a simple deliverable. ## Generating a Simple Deliverable You can generate a simple deliverable in two ways: automatically when the envelope completes, or manually using the Create Deliverable endpoint. ### Automatic (On Envelope Completion) To generate a simple deliverable instead of the default standard deliverable, set the `deliverable` property when creating the envelope: ```json // POST https://api.signatureapi.com/v1/envelopes // X-API-Key: key_test_... // Content-Type: application/json { "title": "Service Agreement", "documents": [ //... ], "recipients": [ //... ], "deliverable": { "type": "simple" } } ``` ### Manual (Create Deliverable Endpoint) You can also create a simple deliverable manually at any time after the envelope completes, using the Create Deliverable (/docs/api/resources/deliverables/create) endpoint. ```json // POST https://api.signatureapi.com/v1/envelopes/{envelope_id}/deliverables // X-API-Key: key_test_... // Content-Type: application/json { "type": "simple" } ``` ## Customization ### Included Documents The `included_documents` property specifies which documents from the envelope to include in the deliverable. By default, all documents are included. Accepts between 1 and 10 document keys. Use this to generate separate deliverables for different documents, or to exclude certain documents from the final PDF. ```json { "type": "simple", "included_documents": ["contract", "addendum"] } ``` ## Password Protection To protect your deliverable with password encryption, see Password Protection (/docs/api/resources/deliverables/password). ## Keep Learning - Follow the Get Deliverables Without the Audit Log (/docs/api/guides/how-to/deliverable-without-audit-log) guide for a step-by-step walkthrough. - Download signed documents (/docs/api/guides/use-cases/save-signed-documents) automatically using webhooks. ## Protect your deliverable with a password URL: https://signatureapi.com/docs/api/resources/deliverables/password Description: Protect your deliverable with password encryption. You can protect a deliverable with password encryption by including a `password` property in your request. Recipients must enter the password to open the PDF. The deliverable PDF is encrypted with AES-128 encryption. ```json Deliverable (Request) { "type": "standard", "password": "SecurePass123", //... } ``` Password protection must be enabled on your account before use. Contact support (/support) to enable this feature. ## Password Requirements - Between 4 and 32 characters - Uppercase letters (A-Z), lowercase letters (a-z), and numbers (0-9) only - Special characters are not supported due to PDF reader compatibility For strong protection, use at least 12 characters with a random mix of uppercase letters, lowercase letters, and numbers. ## API Response In API responses, the password is always masked as `********`. ```json Deliverable (Response) { "type": "standard", "password": "********", //... } ``` ## Verify a Deliverable URL: https://signatureapi.com/docs/api/resources/deliverables/verification Description: Verify the cryptographic signature on SignatureAPI PDF deliverables using public key certificates. All SignatureAPI PDF deliverables are sealed with a cryptographic signature. You can verify that a deliverable was generated by SignatureAPI and has not been altered since it was issued. The signature is created using one of these public key certificates: FieldValue Serial Number0FE117EE6AF5B1EECC367D06D7845D17 SHA-256 Fingerprint843AA9BB894A3C9956F6CD3F06E0D6E9E43F0A192849977F747F918A1C4F4F7E ### Download .cer file Link: https://pub-a1497b6ba2804e8ab872d1e3c152d7cd.r2.dev/SignatureAPI_0FE1.cer FieldValue Serial Number2979AC8352AC3B82B72EAA318FFFA49D SHA-256 Fingerprint815B8B425132FEB359334E4589CC8C7FE78C3F6DC976AB403825DFAC4F0B8CA2 ### Download .cer file Link: https://pub-a1497b6ba2804e8ab872d1e3c152d7cd.r2.dev/SignatureAPI_2979.cer FieldValue Serial Number2E8766982802E57E49D02FA3907DCDCE SHA-256 FingerprintCBD80A0B0B3F212C30590AF00DE75692D11CA9EA49C9B86FD82441BBB0A95BFA ### Download .cer file Link: https://pub-a1497b6ba2804e8ab872d1e3c152d7cd.r2.dev/SignatureAPI_2E87.cer FieldValue Serial Number3C2A804C599D18452298B145296FD433 SHA-256 Fingerprint1B:F6:EA:62:5A:52:E5:36:B2:D9:0F:DA:8B:28:0A:41:58:11:80:7D:4F:B9:24:25:3A:A2:E1:84:C1:30:CC:46 ### Download .cer file Link: https://pub-a1497b6ba2804e8ab872d1e3c152d7cd.r2.dev/SignatureAPI_3C2A.cer FieldValue Serial Number533ECFDBD0D3D876C4D452E2268A3F35 SHA-256 FingerprintDC0B3B18804DC36ECE893C4A4D1C03F156C1D14F5991599DD85DFB9F6D1F7F60 ### Download .cer file Link: https://pub-a1497b6ba2804e8ab872d1e3c152d7cd.r2.dev/SignatureAPI_533E.cer FieldValue Serial Number5DC2DACB8E8B3A32A387FBBED05FD79C SHA-256 Fingerprint0638C6E40EB36D081A1FF578BCDB26799C96716CE4C021F3DB9B9CDC79CB0497 ### Download .cer file Link: https://pub-a1497b6ba2804e8ab872d1e3c152d7cd.r2.dev/SignatureAPI_5DC2.cer ## Verifying in Adobe Acrobat The easiest way to verify a deliverable is to open it in Adobe Acrobat Reader (free) or Adobe Acrobat (paid). **Step 1: Check that the signature is valid.** You should see a signature icon with a green check mark and the message "Signed and all signatures are valid." Image: Valid Signature Message in Adobe Acrobat (/docs/images/verification.png) **Step 2: Open the Signature Panel.** Click the signature panel to review the signer identity and confirm that the certificate matches one of the SignatureAPI certificates listed above. This confirms the deliverable was generated by SignatureAPI and has not been modified since it was sealed. ## Create a deliverable URL: https://signatureapi.com/docs/api/resources/deliverables/create Description: Creates a new deliverable from a completed envelope. Creates a new deliverable (/docs/api/resources/deliverables/object) from a completed envelope (/docs/api/resources/envelopes/object). The envelope must have a `status` of `completed`. SignatureAPI already creates one deliverable automatically when an envelope completes. Use this endpoint to generate additional deliverables after that point. For example, create a simple deliverable containing only specific documents, or a password-protected copy for secure distribution. The deliverable starts in `processing` status and transitions to `generated` once the PDF is ready. This usually takes a few seconds. Subscribe to the `deliverable.generated` (/docs/api/resources/events/deliverable-events#deliverable-generated) webhook to be notified when the deliverable is ready for download. Deliverables created using this endpoint are not sent automatically to recipients. ### Path Parameters The unique identifier of the envelope, in UUID format. ### Body Parameters ### Standard Deliverable The standard deliverable includes an audit log. To get signed documents without an audit log, use the simple deliverable (/docs/api/resources/deliverables/simple) instead. A user-provided name for this deliverable. Use this to identify deliverables when an envelope has more than one. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Between 1 and 32 characters. The type of the deliverable. - `standard`: Includes the signed documents and an audit log with a certificate of completion. This is the default. - `simple`: Includes the signed documents only, without an audit log. For standard deliverables, the type is `standard`. The language for system-generated text in the audit log, including labels and the certificate of completion. Does not affect the content of the signed documents. Supported values: `en` (English), `es` (Spanish), `fr` (French), `it` (Italian), `pt` (Portuguese), `de` (German), `zh` (Chinese Simplified), `hu` (Hungarian). Defaults to the envelope language. The timezone used for timestamps in the audit log. Must be a valid IANA Time Zone Database identifier (e.g., `America/New_York`, `Europe/London`). Does not affect timestamps inside the signed documents. Defaults to the envelope timezone. The format for timestamps in the audit log. Uses MomentJS format tokens (e.g., `MM/DD/YYYY HH:mm:ss`). Does not affect timestamps inside the signed documents. Defaults to the envelope timestamp format. The keys of the documents to include in the deliverable. By default, all documents in the envelope are included. Use this to create a deliverable with only a subset of documents. For example, generate separate deliverables for different recipients. Accepts between 1 and 10 document keys. The password used to encrypt the deliverable. Recipients must enter this password to access the downloaded file. Password requirements: - Between 4 and 32 characters - Letters and numbers only (no special characters or spaces) When returned in API responses, the password value is masked for security (displayed as `********`). Password protection is available upon request. Contact support (/support) to enable this feature. ### Simple Deliverable The simple deliverable does not include an audit log. To get signed documents with an audit log, use the standard deliverable (/docs/api/resources/deliverables/standard) instead. A user-provided name for this deliverable. Use this to identify deliverables when an envelope has more than one. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Between 1 and 32 characters. The type of the deliverable. - `standard`: Includes the signed documents and an audit log with a certificate of completion. This is the default. - `simple`: Includes the signed documents only, without an audit log. For simple deliverables, the type is `simple`. The keys of the documents to include in the deliverable. By default, all documents in the envelope are included. Use this to create a deliverable with only a subset of documents. For example, generate separate deliverables for different recipients. Accepts between 1 and 10 document keys. The password used to encrypt the deliverable. Recipients must enter this password to access the downloaded file. Password requirements: - Between 4 and 32 characters - Letters and numbers only (no special characters or spaces) When returned in API responses, the password value is masked for security (displayed as `********`). Password protection is available upon request. Contact support (/support) to enable this feature. ### Returns Returns a `201 Created` status code along with a deliverable object (/docs/api/resources/deliverables/object) after successful creation, or an error (/docs/api/errors) otherwise. ```json Standard // POST https://api.signatureapi.com/v1/envelopes/{envelope_id}/deliverables // X-API-Key: key_test_... // Content-Type: application/json { "type": "standard" } ``` ```json Simple (No Audit Log) // POST https://api.signatureapi.com/v1/envelopes/{envelope_id}/deliverables // X-API-Key: key_test_... // Content-Type: application/json { "type": "simple" } ``` ```json With Password // POST https://api.signatureapi.com/v1/envelopes/{envelope_id}/deliverables // X-API-Key: key_test_... // Content-Type: application/json { "type": "standard", "password": "SecurePass123", "language": "en", "timezone": "America/New_York", "timestamp_format": "MM/DD/YYYY HH:mm:ss" } ``` ```json With Subset of Documents // POST https://api.signatureapi.com/v1/envelopes/{envelope_id}/deliverables // X-API-Key: key_test_... // Content-Type: application/json { "type": "standard", "included_documents": ["contract", "addendum"] } ``` ```json Standard // HTTP/1.1 201 Created { "id": "del_LXRDwyTeJDVrWXmjwxsAGPq", "name": null, "envelope_id": "4ec99c57-4430-4d73-8afd-912dcf4b5880", "type": "standard", "status": "processing", "url": null, "language": "en", "timezone": "America/New_York", "timestamp_format": "MM/DD/YYYY HH:mm:ss", "included_documents": ["contract", "addendum"], "password": null, "created_at": "2024-01-01T00:00:00Z", "generated_at": null } ``` ```json Simple (No Audit Log) // HTTP/1.1 201 Created { "id": "del_MYSExzUfKEWsXYnkywsAGQr", "name": null, "envelope_id": "4ec99c57-4430-4d73-8afd-912dcf4b5880", "type": "simple", "status": "processing", "url": null, "included_documents": ["contract", "addendum"], "password": null, "created_at": "2024-01-01T00:00:00Z", "generated_at": null } ``` ```json With Password // HTTP/1.1 201 Created { "id": "del_NZTFyAVgLFXtYZolzxtAHRs", "name": null, "envelope_id": "4ec99c57-4430-4d73-8afd-912dcf4b5880", "type": "standard", "status": "processing", "url": null, "language": "en", "timezone": "America/New_York", "timestamp_format": "MM/DD/YYYY HH:mm:ss", "included_documents": ["contract", "addendum"], "password": "********", "created_at": "2024-01-01T00:00:00Z", "generated_at": null } ``` ```json With Subset of Documents // HTTP/1.1 201 Created { "id": "del_OATGzBWhMGYuZApmAyuBISt", "name": null, "envelope_id": "4ec99c57-4430-4d73-8afd-912dcf4b5880", "type": "standard", "status": "processing", "url": null, "language": "en", "timezone": "America/New_York", "timestamp_format": "MM/DD/YYYY HH:mm:ss", "included_documents": ["contract", "addendum"], "password": null, "created_at": "2024-01-01T00:00:00Z", "generated_at": null } ``` ## Retrieve a deliverable URL: https://signatureapi.com/docs/api/resources/deliverables/get Description: Retrieves the details of a deliverable, including its current status and download URL. Retrieves the details of a deliverable, including its current status and download URL. When the deliverable `status` is `generated`, the response includes a `url` property with a download link. By default, this is a pre-signed URL that expires after 1 hour. Call this endpoint again to get a fresh URL if the previous one has expired. ### Path Parameters The unique identifier for this deliverable. ### Returns Returns a `200 OK` status code along with a deliverable object (/docs/api/resources/deliverables/object) if successful, or an error (/docs/api/errors) otherwise. ```json // GET https://api.signatureapi.com/v1/deliverables/{deliverable_id} // X-API-Key: key_test_... ``` ```json // HTTP/1.1 200 OK { "id": "del_LXRDwyTeJDVrWXmjwxsAGPq", "name": null, "envelope_id": "4ec99c57-4430-4d73-8afd-912dcf4b5880", "type": "standard", "status": "generated", "url": "https://vault.signatureapi.com/envelopes/4ec99c57-4430-4d73-8afd-912dcf4b5880/deliverables/del_LXRDwyTeJDVrWXmjwxsAGPq...", "language": "en", "timezone": "America/New_York", "timestamp_format": "MM/DD/YYYY HH:mm:ss", "included_documents": ["contract", "addendum"], "password": null, "created_at": "2024-01-01T00:00:00Z", "generated_at": "2024-01-01T00:01:00Z" } ``` ## List deliverables URL: https://signatureapi.com/docs/api/resources/deliverables/list Description: Returns a list of all deliverables for an envelope. Returns a list of all deliverables for an envelope. Every completed envelope has at least one deliverable, created automatically when the envelope completes. Additional deliverables may exist if created via the Create Deliverable (/docs/api/resources/deliverables/create) endpoint. Results are sorted chronologically by creation date, with the earliest deliverable appearing first. ### Path Parameters The unique identifier of the envelope, in UUID format. ### Query Parameters The maximum number of objects to return in the response, up to 20. The default is 20. For certain use cases we can increase the limit. Please contact support (mailto:support@signatureapi.com). ### Returns Returns a `200 OK` status code along with a paginated (/docs/api/pagination) list of deliverable objects (/docs/api/resources/deliverables/object) if successful, or an error (/docs/api/errors) otherwise. ```json // GET https://api.signatureapi.com/v1/envelopes/{envelope_id}/deliverables // X-API-Key: key_test_... ``` ```json // HTTP/1.1 200 OK { "links": { "next": null, "previous": null }, "data": [ { "id": "del_LXRDwyTeJDVrWXmjwxsAGPq", "name": null, "envelope_id": "4ec99c57-4430-4d73-8afd-912dcf4b5880", "type": "standard", "status": "generated", //... }, { "id": "del_MYSExzUfKEWsXYnkywsAGQr", "name": "hr_pack", "envelope_id": "4ec99c57-4430-4d73-8afd-912dcf4b5880", "type": "simple", "status": "generated", //... } ] } ``` ## Ceremony URL: https://signatureapi.com/docs/api/resources/ceremonies/object Description: The ceremony object represents a signing session where a recipient interacts with an envelope. A ceremony is the session where a recipient authenticates and acts on an envelope. Depending on the recipient type, those actions include signing, approving, or preparing documents. Each recipient has one active ceremony at a time. Creating a new ceremony for a recipient automatically revokes any previous ceremony. A ceremony belongs to a recipient (/docs/api/resources/recipients/object). ## Lifecycle A ceremony's `status` tracks the recipient's progress. See the ceremony lifecycle (/docs/api/resources/ceremonies/lifecycle) for details on each status. ## Attributes ### Email Link Authentication With **email link authentication**, the recipient receives an email with a direct link to the ceremony. Clicking the link authenticates the recipient and opens the signing session. The type of authentication. Available values: `email_link`, `email_code`, and `custom`. For email link authentication, this value is `email_link`. The custom subject line used for this recipient's invitation email. `null` if the envelope title is used. The custom message body used for this recipient's invitation email. `null` if the envelope message is used. ### Email Code Authentication With **email code authentication**, the recipient receives an email from SignatureAPI containing a 9-digit code. The recipient must enter this code to authenticate and access the ceremony. The type of authentication. Available values: `email_link`, `email_code`, and `custom`. For email code authentication, this value is `email_code`. ### Custom Authentication With **custom authentication**, your application authenticates the recipient. SignatureAPI provides a ceremony URL that you share or embed in your application to give the recipient access. The type of authentication. Available values: `email_link`, `email_code`, and `custom`. For custom authentication, this value is `custom`. The name of your company or application that authenticated the recipient. This value appears in the envelope audit log as the authentication provider. Key-value pairs with metadata about the authentication event, such as timestamps, session IDs, and user identifiers. These values appear in the envelope audit log. The values in `data` must be sufficient to verify how the recipient was authenticated. You must retain all records needed to prove the recipient's authentication, such as session information. In cases such as legal proceedings, you may need to provide these records to confirm identity. Review our Terms & Conditions (/docs/legal/terms/terms) for details. An HTTPS URL to redirect the recipient to after the ceremony finishes. Learn more in Redirect URL (/docs/api/resources/ceremonies/redirect-url). The delay in seconds before the ceremony redirects to `redirect_url` (standalone ceremonies) or emits completion events (embedded ceremonies). Defaults to `3`. Allowed range: `0` to `20`. Learn more in Redirect URL (/docs/api/resources/ceremonies/redirect-url). The format of the ceremony URL. Available options: - `standard` (default): Full-length URL. Works for most use cases. - `short`: Shortened URL. Use this when sharing through space-constrained channels such as SMS or push notifications. Origins allowed to embed this ceremony in an iframe. These values set the `frame-ancestors` directive in the ceremony's Content Security Policy (CSP) header. Sources typically take the form of a scheme and host (for example, `https://app.example.com`). Wildcards are supported (for example, `https://*.example.com`). For all available options, see the frame-ancestors documentation (https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/frame-ancestors#sources). Defaults to an empty list (`[]`), which means embedding is not allowed. To allow embedding from all origins (not recommended for production), use `["*"]`. Only the origin (scheme and host) is used. Paths are ignored. The URL where the recipient can access the ceremony. You can share this link with the recipient directly or embed it in your application. This property is `null` when: - The ceremony uses `email_link` authentication. SignatureAPI delivers the URL by email in that case. - The ceremony is not active (for example, it is completed, revoked, or declined). The URL expires 30 days after creation, or when a new ceremony is created for the same recipient. ```json Email Link { "authentication": [ { "type": "email_link", "subject_override": null, "message_override": null } ], "redirect_url": null, "redirect_delay": 3, "embeddable_in": [], "url_variant": "standard", "url": null } ``` ```json Email Code { "authentication": [ { "type": "email_code" } ], "redirect_url": null, "redirect_delay": 3, "embeddable_in": [], "url_variant": "standard", "url": "https://sign.signatureapi.com/en/start?token=eyJhbGciOiJFUzI1NiIsInR..." } ``` ```json Custom Auth { "authentication": [ { "type": "custom", "provider": "SuperApp", "data": { "Session ID": "se_88620999344", "Authenticated At": "Dec 31, 2025 23:59:59" } } ], "redirect_url": "https://www.example.com/redirect", "redirect_delay": 5, "embeddable_in": [ "https://app.example.com" ], "url_variant": "standard", "url": "https://sign.signatureapi.com/en/start?token=eyJhbGciOiJFUzI1NiIsInR..." } ``` ## Ceremony Lifecycle URL: https://signatureapi.com/docs/api/resources/ceremonies/lifecycle Description: The lifecycle and statuses of a ceremony. A ceremony's `status` tracks the recipient's progress through their signing session. | Status | Description | |--------|-------------| | `pending` | The ceremony was created but the envelope is not yet active. | | `active` | The ceremony is ready for the recipient to access. | | `completed` | The recipient finished their actions. | | `declined` | The recipient declined to act. | | `revoked` | The ceremony was replaced by a new ceremony or the envelope was canceled. | ## Ceremony URL URL: https://signatureapi.com/docs/api/resources/ceremonies/ceremony-url Description: Learn how to obtain the ceremony URL to deliver signing access yourself or embed the ceremony in your application. Recipients use the ceremony URL to access their signing ceremony and complete their actions. By default, SignatureAPI creates a ceremony for each recipient when you create an envelope. It uses email link authentication and sends the recipient an email with their ceremony link. You don't need to handle URL delivery in that case. You may want to obtain the ceremony URL directly to: - Embed (/docs/embedded/introduction) the signing ceremony in your web or mobile application - Redirect users to the ceremony from within your application workflow - Send the invitation through your own email infrastructure with custom branding ## When ceremony URLs are available A ceremony URL is available when the ceremony is active and not yet completed. If the first authentication method is `email_link`, SignatureAPI delivers the URL by email. The `url` property will be `null` in that case. When SignatureAPI sends the URL directly to the recipient (as with Email Link Authentication (/docs/api/resources/ceremonies/authentication/email-link)), the `url` property is `null`. You don't need to handle delivery yourself. ## How to get a ceremony URL Set the ceremony's authentication method to one of the following: - Email Code (/docs/api/resources/ceremonies/authentication/email-code) - Custom Authentication (/docs/api/resources/ceremonies/authentication/custom) - Multiple Authentication (/docs/api/resources/ceremonies/authentication/multiple) with Email Code or Custom Authentication as the first step The URL is returned in the `url` property of the ceremony object. You can retrieve it in several ways. ### From envelope operations When you create or retrieve an envelope, the ceremony URL is available in the `url` property of each recipient's ceremony object. ```json Envelope object { "id": "abcdef12-3456-7890-1234-abcdef123456", "title": "Service Agreement", "recipients": [ { "type": "signer", "key": "client", "name": "John Doe", "email": "john.doe@example.com", "ceremony": { "authentication": [ { "type": "email_code" } ], "url": "https://sign.signatureapi.com/en/start?token=eyJhbGciOiJFUzI1NiIsInR...", //... } //... } ] //... } ``` ### From recipient operations When you retrieve a recipient, the ceremony URL is available in the `url` property of the recipient's ceremony object. ```json Recipient object { "type": "signer", "key": "client", "name": "John Doe", "email": "john.doe@example.com", "ceremony": { "authentication": [ { "type": "email_code" } ], "url": "https://sign.signatureapi.com/en/start?token=eyJhbGciOiJFUzI1NiIsInR...", //... } //... } ``` ### From ceremony operations When you create a ceremony using the Create Ceremony (/docs/api/resources/ceremonies/create) endpoint, the URL is returned in the `url` property of the ceremony object. ```json Ceremony object { "authentication": [ { "type": "email_code" } ], "url": "https://sign.signatureapi.com/en/start?token=eyJhbGciOiJFUzI1NiIsInR...", //... } ``` ## Short ceremony URLs Standard ceremony URLs are long. They may not fit in space-constrained channels like SMS or push notifications. Set `url_variant` to `short` when creating the ceremony to generate a shorter URL. ```json // POST https://api.signatureapi.com/v1/recipients/{recipient_id}/ceremonies // X-API-Key: key_test_... // Content-Type: application/json { "authentication": [ { "type": "custom", "provider": "SuperApp", "data": { "Session ID": "a4f9e8b2-7c1d-4b2d-9a4b-e0c5d6f7a1b3", "Authenticated At": "2025-12-31T23:59:59Z" } } ], "url_variant": "short" } ``` ```json // HTTP/1.1 201 Created { //... "url": "https://sign.signatureapi.com/s/BgnexxxxxxxxIbRi" } ``` ## URL expiration A ceremony URL stops working when any of these happens: - **Its validity ends.** Each URL is valid for 30 days by default. Contact support to adjust the period. - **A new ceremony replaces it.** Creating a new ceremony for the same recipient revokes every earlier URL. - **The recipient completes or declines the ceremony.** After that, the URL only reports that the ceremony is already completed. - **The envelope is canceled or the recipient is replaced.** The URL then reports `not_available`. How to get a new URL depends on the authentication method and URL variant: | Authentication | Standard URL | Short URL | |----------------|--------------|-----------| | Email Link (/docs/api/resources/ceremonies/authentication/email-link) | Resend (/docs/api/resources/recipients/resend) or Create Ceremony (/docs/api/resources/ceremonies/create) | Create Ceremony (/docs/api/resources/ceremonies/create) | | Email Code (/docs/api/resources/ceremonies/authentication/email-code) | Get Envelope (/docs/api/resources/envelopes/get) | Create Ceremony (/docs/api/resources/ceremonies/create) | | Custom (/docs/api/resources/ceremonies/authentication/custom) | Get Envelope (/docs/api/resources/envelopes/get) | Create Ceremony (/docs/api/resources/ceremonies/create) | Short URLs do not refresh automatically. Create a new ceremony to generate a new short URL. ## Invalid or expired links Recipients may see an "Invalid link" error when accessing a ceremony URL. Common causes: - **The URL expired.** Ceremony URLs are valid for 30 days by default. Create a new ceremony to generate a fresh URL. - **A newer ceremony replaced it.** Creating a new ceremony for the same recipient invalidates the previous URL. Only URLs for the most recent ceremony work. - **The envelope was canceled or completed.** Ceremony URLs stop working after the envelope reaches a terminal status. - **The URL was modified.** The full URL, including the token, must be used exactly as returned by the API. Truncated or modified URLs will not work. If a recipient reports an invalid link, check the envelope and recipient status first. If the envelope is still in progress, create a new ceremony (/docs/api/resources/ceremonies/create) to generate a new URL. ## A new URL on every read For `standard` URLs, every read of the envelope or recipient returns a new `url` for the same ceremony, each with its own validity (30 days by default). Earlier URLs keep working until they expire. A `short` URL stays the same until it expires. A ceremony URL is a bearer credential: anyone who has it can open the ceremony. Don't log it or store it on a device. To resume a ceremony later, ask your server for the current URL. ## Revoked and completed links A revoked or completed URL still loads the ceremony page and returns HTTP 200. The page reports the failure to the signer, and an embedded ceremony sends `ceremony.failed` with an error type (/docs/embedded/ceremony-events#error-types). A plain HTTP request can't tell you whether a URL is still valid, so don't use one to check. ## Redirect URL URL: https://signatureapi.com/docs/api/resources/ceremonies/redirect-url Description: Configure where recipients are sent after completing, declining, or failing a signing ceremony. After a standalone ceremony finishes (completed, declined, or failed), SignatureAPI redirects the recipient to the `redirect_url` you defined on the ceremony object. SignatureAPI appends the following query parameters to the URL: | Parameter | Description | |:----------|:------------| | `ceremony_result` | The outcome: `ceremony.completed`, `ceremony.declined`, or `ceremony.failed`. | | `envelope_id` | The ID of the envelope. | | `recipient_id` | The ID of the recipient. | For example, if `redirect_url` is `https://www.example.com`, a successful ceremony redirects to: `https://www.example.com/?ceremony_result=ceremony.completed&envelope_id=5b7be28c-6c7c-4aaa-b25f-66879e8d0957&recipient_id=re_0sgQC0cejYRC8wRsT5N9ll` Use these query parameters to process the ceremony result in your application. ## Redirect delay By default, the result page shows for 3 seconds before the redirect. Set the `redirect_delay` property to change this. ```json // POST https://api.signatureapi.com/v1/recipients/{recipient_id}/ceremonies // X-API-Key: key_test_... // Content-Type: application/json { "authentication": [{ "type": "email_code" }], "redirect_url": "https://www.example.com/success", "redirect_delay": 0 } ``` Set `redirect_delay` to `0` for an immediate redirect. The maximum value is `20` seconds. For embedded ceremonies, `redirect_delay` controls how long the result page shows before the ceremony sends `ceremony.completed` or `ceremony.declined`. Set it to `0` to hand control back to your app immediately, so your app can show its own result screen. Learn more in Ceremony Events (/docs/embedded/ceremony-events). Embedded ceremonies (with `embedded=true` on the URL) ignore `redirect_url`: leave it unset. They send Ceremony Events (/docs/embedded/ceremony-events) instead, including in native mobile apps. ## Create a ceremony URL: https://signatureapi.com/docs/api/resources/ceremonies/create Description: Create a new signing ceremony for a recipient with custom authentication options. Creates a new ceremony (/docs/api/resources/ceremonies/object) for a recipient (/docs/api/resources/recipients/object). Any previous active ceremony for the recipient is automatically revoked. The `authentication` array specifies which authentication methods the recipient must complete to access the ceremony. You can configure multiple methods. Recipients complete them in sequence. Learn more in Recipient Authentication (/docs/api/resources/ceremonies/authentication/overview). ## Path Parameters The unique identifier of the recipient. Recipient IDs use the `re_` prefix. ## Body Parameters #### `authentication` (array of authentication object, required) ### Email Link Authentication With **email link authentication**, the recipient receives an email with a direct link to the ceremony. Clicking the link authenticates the recipient and opens the signing session. The type of authentication. Available values: `email_link`, `email_code`, and `custom`. For email link authentication, set `type` to `email_link`. A custom subject line for the invitation email sent to this recipient. When not set, the subject defaults to the envelope title (/docs/api/resources/envelopes/object#param-title). Maximum 500 characters. A custom message body for the invitation email sent to this recipient. When not set, the message defaults to the envelope message (/docs/api/resources/envelopes/object#param-message). Supports Markdown formatting: `**bold**`, `*italic*`, and `\n\n` for paragraph breaks. Maximum 2000 characters. ### Email Code Authentication With **email code authentication**, the recipient receives an email from SignatureAPI containing a 9-digit code. The recipient must enter this code to authenticate and access the ceremony. The type of authentication. Available values: `email_link`, `email_code`, and `custom`. For email code authentication, set `type` to `email_code`. ### Custom Authentication With **custom authentication**, your application authenticates the recipient. SignatureAPI provides a ceremony URL that you share or embed in your application to give the recipient access. The type of authentication. Available values: `email_link`, `email_code`, and `custom`. For custom authentication, set `type` to `custom`. The name of your company or application that authenticated the recipient. This value appears in the envelope audit log as the authentication provider. Key-value pairs with metadata about the authentication event, such as timestamps, session IDs, and user identifiers. These values appear in the envelope audit log. The values in `data` must be sufficient to verify how the recipient was authenticated. You must retain all records needed to prove the recipient's authentication, such as session information. In cases such as legal proceedings, you may need to provide these records to confirm identity. Review our Terms & Conditions (/docs/legal/terms/terms) for details. #### `redirect_url` (string) An HTTPS URL to redirect the recipient to after the ceremony finishes. Learn more in Redirect URL (/docs/api/resources/ceremonies/redirect-url). #### `redirect_delay` (integer) The delay in seconds before the ceremony redirects to `redirect_url` (standalone ceremonies) or emits completion events (embedded ceremonies). Defaults to `3`. Allowed range: `0` to `20`. Learn more in Redirect URL (/docs/api/resources/ceremonies/redirect-url). #### `url_variant` (enum) The format of the ceremony URL. Available options: - `standard` (default): Full-length URL. Works for most use cases. - `short`: Shortened URL. Use this when sharing through space-constrained channels such as SMS or push notifications. #### `embeddable_in` (array of strings) Origins allowed to embed this ceremony in an iframe. These values set the `frame-ancestors` directive in the ceremony's Content Security Policy (CSP) header. Sources typically take the form of a scheme and host (for example, `https://app.example.com`). Wildcards are supported (for example, `https://*.example.com`). For all available options, see the frame-ancestors documentation (https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/frame-ancestors#sources). Defaults to an empty list (`[]`), which means embedding is not allowed. To allow embedding from all origins (not recommended for production), use `["*"]`. Only the origin (scheme and host) is used. Paths are ignored. ## Returns Returns a `201 Created` status code with a ceremony object (/docs/api/resources/ceremonies/object) on success, or an error (/docs/api/errors) otherwise. ```json Email Link // POST https://api.signatureapi.com/v1/recipients/{recipient_id}/ceremonies // X-API-Key: key_test_... // Content-Type: application/json { "authentication": [ { "type": "email_link", "subject_override": "Please sign the Service Agreement", "message_override": "Please review and sign the attached agreement." } ] } ``` ```json Email Code // POST https://api.signatureapi.com/v1/recipients/{recipient_id}/ceremonies // X-API-Key: key_test_... // Content-Type: application/json { "authentication": [ { "type": "email_code" } ] } ``` ```json Custom // POST https://api.signatureapi.com/v1/recipients/{recipient_id}/ceremonies // X-API-Key: key_test_... // Content-Type: application/json { "authentication": [ { "type": "custom", "provider": "SuperApp", "data": { "Session ID": "se_88620999344", "Authenticated At": "2025-12-31T23:59:59Z" } } ], "embeddable_in": [ "https://superapp.example.com" ] } ``` ```json With Redirect URL // POST https://api.signatureapi.com/v1/recipients/{recipient_id}/ceremonies // X-API-Key: key_test_... // Content-Type: application/json { "authentication": [ { "type": "email_link" } ], "redirect_url": "https://example.com/signing-complete", "redirect_delay": 5 } ``` ```json Embeddable // POST https://api.signatureapi.com/v1/recipients/{recipient_id}/ceremonies // X-API-Key: key_test_... // Content-Type: application/json { "authentication": [ { "type": "custom", "provider": "MyApp", "data": { "user_id": "usr_12345" } } ], "embeddable_in": [ "https://app.example.com", "https://staging.example.com" ], "redirect_url": "https://app.example.com/done" } ``` ```json Email Link // HTTP/1.1 201 Created { "authentication": [ { "type": "email_link", "subject_override": "Please sign the Service Agreement", "message_override": "Please review and sign the attached agreement." } ], "embeddable_in": [], "redirect_url": null, "redirect_delay": 3, "url_variant": "standard", "url": null } ``` ```json Email Code // HTTP/1.1 201 Created { "authentication": [ { "type": "email_code" } ], "embeddable_in": [], "redirect_url": null, "redirect_delay": 3, "url_variant": "standard", "url": "https://sign.signatureapi.com/en/start?token=eyJhbGciOiJFUzI1NiIsInR..." } ``` ```json Custom // HTTP/1.1 201 Created { "authentication": [ { "type": "custom", "provider": "SuperApp", "data": { "Session ID": "se_88620999344", "Authenticated At": "2025-12-31T23:59:59Z" } } ], "embeddable_in": [ "https://superapp.example.com" ], "redirect_url": null, "redirect_delay": 3, "url_variant": "standard", "url": "https://sign.signatureapi.com/en/start?token=eyJhbGciOiJFUzI1NiIsInR..." } ``` ```json With Redirect URL // HTTP/1.1 201 Created { "authentication": [ { "type": "email_link" } ], "embeddable_in": [], "redirect_url": "https://example.com/signing-complete", "redirect_delay": 5, "url_variant": "standard", "url": null } ``` ```json Embeddable // HTTP/1.1 201 Created { "authentication": [ { "type": "custom", "provider": "MyApp", "data": { "user_id": "usr_12345" } } ], "embeddable_in": [ "https://app.example.com", "https://staging.example.com" ], "redirect_url": "https://app.example.com/done", "redirect_delay": 3, "url_variant": "standard", "url": "https://sign.signatureapi.com/en/start?token=eyJhbGciOiJFUzI1NiIsInR..." } ``` ## Event URL: https://signatureapi.com/docs/api/resources/events/object Description: The event object records changes and actions in your account, delivered via webhooks or retrievable through the API. Events record changes and actions in your SignatureAPI account. Examples include an envelope completing (/docs/api/resources/events/envelope-events#envelope-completed) and a recipient email bouncing (/docs/api/resources/events/recipient-events#recipient-hard-bounced). You receive events as webhook notifications. You can also retrieve them through the API, either for all events in your account (/docs/api/resources/events/all) or for a specific envelope (/docs/api/resources/events/envelope) or recipient (/docs/api/resources/events/recipient). ## Typical event flow A standard signing flow produces events in this order: 1. `envelope.created`: Envelope is created and processing begins. 2. `envelope.started`: Processing complete, recipients are being notified. 3. `recipient.released`: Recipient is ready to receive an invitation. 4. `recipient.sent`: Invitation email delivered (only when the ceremony uses `email_link` authentication). 5. `recipient.accessed`: Recipient opens the ceremony URL. 6. `recipient.viewed`: Recipient authenticates and views the documents. 7. `recipient.completed`: Recipient finishes signing. 8. `envelope.completed`: All recipients done, envelope is complete. 9. `deliverable.generated`: Signed PDF is ready for download. For sequential routing, steps 3-7 repeat for each recipient in order. For parallel routing, multiple recipients go through steps 3-7 at the same time. Events may arrive out of order. Your application should handle this gracefully. See Webhooks (/docs/api/webhooks) for delivery details. ## Attributes The unique identifier of the event. Uses the `evt_` prefix. The type of the event. Determines the category and the shape of the `data` payload. Event types are grouped into four categories: envelope, recipient, deliverable, and sender. For the full list of event types, see: - Envelope Events (/docs/api/resources/events/envelope-events) - Recipient Events (/docs/api/resources/events/recipient-events) - Deliverable Events (/docs/api/resources/events/deliverable-events) - Sender Events (/docs/api/resources/events/sender-events) When the event occurred, in ISO 8601 format. The data associated with the event. The shape of this object depends on the event `type`. ### Envelope event data These properties are common to all envelope events. Some event types include additional properties. See Envelope Events (/docs/api/resources/events/envelope-events) for details. The unique identifier of the resource this event refers to. For envelope events, this value is the envelope ID. The type of resource this event refers to. For envelope events, the value is `envelope`. The ID of the envelope this event refers to. For envelope events, this value is the same as `object_id`. The metadata attached to the envelope. ### Recipient event data These properties are common to all recipient events. Some event types include additional properties. See Recipient Events (/docs/api/resources/events/recipient-events) for details. The unique identifier of the resource this event refers to. For recipient events, this value is the recipient ID. The type of resource this event refers to. For recipient events, the value is `recipient`. The ID of the envelope the recipient belongs to. The metadata attached to the envelope the recipient belongs to. The type of the recipient. Possible values: `signer`, `approver`, `preparer`. A user-provided key that identifies the recipient within an envelope. ### Deliverable event data These properties are common to all deliverable events. Some event types include additional properties. See Deliverable Events (/docs/api/resources/events/deliverable-events) for details. The unique identifier of the resource this event refers to. For deliverable events, this value is the deliverable ID. The type of resource this event refers to. For deliverable events, the value is `deliverable`. The ID of the envelope the deliverable belongs to. The metadata attached to the envelope the deliverable belongs to. The type of the deliverable. Possible values: `simple`, `standard`. A user-provided name for the deliverable. The keys of the documents included in the deliverable. ### Sender event data These properties are common to all sender events. Some event types include additional properties. See Sender Events (/docs/api/resources/events/sender-events) for details. The unique identifier of the sender this event refers to. The type of resource this event refers to. For sender events, the value is `sender`. The email address of the sender this event refers to. ```json Example Event { "id": "evt_4p2oouvNvjp1I9ckgqycH2", "type": "recipient.completed", "timestamp": "2025-12-31T15:00:01.999Z", "data": { "object_id": "re_7v7Sion0vqjJioYmwfZ9mf", "object_type": "recipient", "envelope_id": "e387553d-cbb7-4924-abd8-b2d89699e9b5", "envelope_metadata": { "deal_id": "50055", "deal_owner": "Jane C." }, "recipient_type": "signer", "recipient_key": "client", "session_id": "ses_2X6eHBCL84MDGrLQX0mHI72" } } ``` ## Envelope events URL: https://signatureapi.com/docs/api/resources/events/envelope-events Description: Track envelope lifecycle changes including creation, completion, cancellation, and failure. Envelope events track key changes in the lifecycle of an envelope. This page describes each event type, when it fires, and the additional data included in the payload. ## envelope.created Fires when a new envelope is created. The envelope is in `processing` status and has not yet been sent to recipients. Use this event to record that a signing process has started in your system. ```json JSON { "id": "evt_4p2oouvNvjp1I9ckgqycH2", "type": "envelope.created", "timestamp": "2025-12-31T23:59:59.999Z", "data": { "object_id": "e387553d-cbb7-4924-abd8-b2d89699e9b5", "object_type": "envelope", "envelope_id": "e387553d-cbb7-4924-abd8-b2d89699e9b5", "envelope_metadata": { "deal_id": "50055", "deal_owner": "Jane C." } } } ``` ## envelope.started Fires when the envelope finishes processing and transitions from `processing` to `in_progress` status. Recipients are now being notified. For sequential routing, the first recipient receives the signing request. For parallel routing, all recipients receive it at the same time. ```json JSON { "id": "evt_5a2b3c4d5e6f7g8h9i0j", "type": "envelope.started", "timestamp": "2025-12-31T23:59:59.999Z", "data": { "object_id": "e387553d-cbb7-4924-abd8-b2d89699e9b5", "object_type": "envelope", "envelope_id": "e387553d-cbb7-4924-abd8-b2d89699e9b5", "envelope_metadata": { "deal_id": "50055", "deal_owner": "Jane C." } } } ``` ## envelope.completed Fires when all recipients have completed the envelope. The envelope status changes from `in_progress` to `completed`. The deliverable with the signed documents may still be generating when this event is sent. To retrieve or store the signed documents, listen for `deliverable.generated` (/docs/api/resources/events/deliverable-events#deliverable-generated) instead. Use this event to trigger downstream workflows such as storing signed documents, updating records, or notifying your team. ```json JSON { "id": "evt_6b7c8d9e0f1g2h3i4j5k", "type": "envelope.completed", "timestamp": "2025-12-31T23:59:59.999Z", "data": { "object_id": "e387553d-cbb7-4924-abd8-b2d89699e9b5", "object_type": "envelope", "envelope_id": "e387553d-cbb7-4924-abd8-b2d89699e9b5", "envelope_metadata": { "deal_id": "50055", "deal_owner": "Jane C." } } } ``` ## envelope.failed Fires when an envelope encounters an internal error and transitions to `failed` status. The `data.detail` property contains a human-readable explanation of the failure. Envelope failures are very rare. SignatureAPI engineers receive an automatic alert and begin investigating when this event fires. Contact support for additional information. ```json JSON { "id": "evt_7c8d9e0f1g2h3i4j5k6l", "type": "envelope.failed", "timestamp": "2025-12-31T23:59:59.999Z", "data": { "object_id": "e387553d-cbb7-4924-abd8-b2d89699e9b5", "object_type": "envelope", "envelope_id": "e387553d-cbb7-4924-abd8-b2d89699e9b5", "envelope_metadata": { "deal_id": "50055", "deal_owner": "Jane C." }, "detail": "Could not parse input PDF document." } } ``` ## envelope.canceled Fires when the envelope is explicitly canceled by calling the Cancel Envelope (/docs/api/resources/envelopes/cancel) endpoint. The envelope status changes to `canceled`, which is a terminal state. The `data.reason` property contains the cancellation reason if one was provided, or `null` if none was given. ```json JSON { "id": "evt_8d9e0f1g2h3i4j5k6l7m", "type": "envelope.canceled", "timestamp": "2025-12-31T23:59:59.999Z", "data": { "object_id": "e387553d-cbb7-4924-abd8-b2d89699e9b5", "object_type": "envelope", "envelope_id": "e387553d-cbb7-4924-abd8-b2d89699e9b5", "envelope_metadata": { "deal_id": "50055", "deal_owner": "Jane C." }, "reason": "Insurance policy offer expired." } } ``` ## Recipient events URL: https://signatureapi.com/docs/api/resources/events/recipient-events Description: Monitor recipient actions and status changes including signing, bounces, and replacements. Recipient events track key actions and status changes for recipients within an envelope. This page describes each event type, when it fires, and the additional data included in the payload. ## recipient.released Fires when a recipient becomes ready to receive an invitation. The recipient status changes to `pending`. This event fires after all previous recipients in the routing order have completed, or immediately for the first recipient when the envelope starts. ```json JSON { "id": "evt_1a2b3c4d5e6f7g8h9i0j", "type": "recipient.released", "timestamp": "2025-12-31T23:59:59.999Z", "data": { "object_id": "re_00ZeZjRaXCgT30n1eBx53N", "object_type": "recipient", "envelope_id": "e387553d-cbb7-4924-abd8-b2d89699e9b5", "envelope_metadata": { "deal_id": "50055", "deal_owner": "Jane C." }, "recipient_type": "signer", "recipient_key": "client" } } ``` ## recipient.sent Fires when SignatureAPI sends the invitation email to a recipient. The recipient status changes to `sent`. This event only fires for recipients whose ceremony uses `email_link` authentication, because that is the only case where SignatureAPI sends the invitation email. ```json JSON { "id": "evt_2b3c4d5e6f7g8h9i0j1k", "type": "recipient.sent", "timestamp": "2025-12-31T23:59:59.999Z", "data": { "object_id": "re_00ZeZjRaXCgT30n1eBx53N", "object_type": "recipient", "envelope_id": "e387553d-cbb7-4924-abd8-b2d89699e9b5", "envelope_metadata": { "deal_id": "50055", "deal_owner": "Jane C." }, "recipient_type": "signer", "recipient_key": "client" } } ``` ## recipient.accessed Fires when a recipient opens the ceremony URL. To reduce duplicate events, this fires at most once every 60 seconds for the same IP address and user agent combination. The recipient has not yet authenticated at this point. The `data` object includes the recipient's `ip` address, `user_agent`, and a `session_id`. Use `session_id` to correlate multiple events from the same ceremony session. Some security platforms access the ceremony URL to prefetch content or scan for threats. These requests can trigger `recipient.accessed` before the intended recipient opens the link. To confirm that the human recipient has accessed the ceremony, use the `recipient.viewed` event instead. ```json JSON { "id": "evt_2b3c4d5e6f7g8h9i0j1k", "type": "recipient.accessed", "timestamp": "2025-12-31T23:59:59.999Z", "data": { "object_id": "re_00ZeZjRaXCgT30n1eBx53N", "object_type": "recipient", "envelope_id": "e387553d-cbb7-4924-abd8-b2d89699e9b5", "envelope_metadata": { "deal_id": "50055", "deal_owner": "Jane C." }, "recipient_type": "signer", "recipient_key": "client", "ip": "123.122.990.22", "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36", "session_id": "ses_2X6eHBCL84MDGrLQX0mHI72" } } ``` ## recipient.viewed Fires after a recipient authenticates and the documents are displayed in the ceremony. This confirms the recipient passed all authentication steps and can view the documents. The `data` object includes a `session_id`. Use it to correlate multiple events from the same ceremony session. ```json JSON { "id": "evt_2b3c4d5e6f7g8h9i0j1k", "type": "recipient.viewed", "timestamp": "2025-12-31T23:59:59.999Z", "data": { "object_id": "re_00ZeZjRaXCgT30n1eBx53N", "object_type": "recipient", "envelope_id": "e387553d-cbb7-4924-abd8-b2d89699e9b5", "envelope_metadata": { "deal_id": "50055", "deal_owner": "Jane C." }, "recipient_type": "signer", "recipient_key": "client", "session_id": "ses_2X6eHBCL84MDGrLQX0mHI72" } } ``` ## recipient.completed Fires when a recipient finishes all required actions in the ceremony. The recipient status changes to `completed`. For signers, this means they have signed and finalized. For approvers and preparers, this means they have reviewed and submitted their inputs. The `data` object includes a `session_id`. Use it to correlate multiple events from the same ceremony session. ```json JSON { "id": "evt_3c4d5e6f7g8h9i0j1k2l", "type": "recipient.completed", "timestamp": "2025-12-31T23:59:59.999Z", "data": { "object_id": "re_00ZeZjRaXCgT30n1eBx53N", "object_type": "recipient", "envelope_id": "e387553d-cbb7-4924-abd8-b2d89699e9b5", "envelope_metadata": { "deal_id": "50055", "deal_owner": "Jane C." }, "recipient_type": "signer", "recipient_key": "client", "session_id": "ses_2X6eHBCL84MDGrLQX0mHI72" } } ``` ## recipient.rejected Fires when a recipient declines the envelope. A rejection does not cancel the envelope. To move on, either replace the recipient (/docs/api/resources/recipients/replace) or cancel the envelope (/docs/api/resources/envelopes/cancel), through the API or the Dashboard. The `data.reason` property contains the recipient's explanation if they provided one. It is an empty string if no reason was given. The `data` object also includes a `session_id`. ```json JSON { "id": "evt_4d5e6f7g8h9i0j1k2l3m", "type": "recipient.rejected", "timestamp": "2025-12-31T23:59:59.999Z", "data": { "object_id": "re_00ZeZjRaXCgT30n1eBx53N", "object_type": "recipient", "envelope_id": "e387553d-cbb7-4924-abd8-b2d89699e9b5", "envelope_metadata": { "deal_id": "50055", "deal_owner": "Jane C." }, "recipient_type": "signer", "recipient_key": "client", "reason": "Not the terms we agreed to on June.", "session_id": "ses_2X6eHBCL84MDGrLQX0mHI72" } } ``` ## recipient.soft_bounced Fires when the invitation email is temporarily undeliverable. The recipient status changes to `soft_bounced`. Common causes include a full mailbox or a temporary server issue. The `data.detail` property contains the bounce reason from the remote email server. Use the Resend Request (/docs/api/resources/recipients/resend) endpoint to try delivering the invitation again. ```json JSON { "id": "evt_5e6f7g8h9i0j1k2l3m4n", "type": "recipient.soft_bounced", "timestamp": "2025-12-31T23:59:59.999Z", "data": { "object_id": "re_00ZeZjRaXCgT30n1eBx53N", "object_type": "recipient", "envelope_id": "e387553d-cbb7-4924-abd8-b2d89699e9b5", "envelope_metadata": { "deal_id": "50055", "deal_owner": "Jane C." }, "recipient_type": "signer", "recipient_key": "client", "detail": "Server 123.122.990.22 responded with: Mailbox Full" } } ``` ## recipient.hard_bounced Fires when the invitation email is permanently undeliverable. The recipient status changes to `hard_bounced`. Common causes include an invalid or nonexistent email address. The `data.detail` property contains the bounce reason from the remote email server. You can view further details, such as SMTP responses, in the Dashboard. After a hard bounce, you cannot resend to this recipient. Use the Replace Recipient (/docs/api/resources/recipients/replace) endpoint to assign a new person with a valid email address. ```json JSON { "id": "evt_6f7g8h9i0j1k2l3m4n5o", "type": "recipient.hard_bounced", "timestamp": "2025-12-31T23:59:59.999Z", "data": { "object_id": "re_00ZeZjRaXCgT30n1eBx53N", "object_type": "recipient", "envelope_id": "e387553d-cbb7-4924-abd8-b2d89699e9b5", "envelope_metadata": { "deal_id": "50055", "deal_owner": "Jane C." }, "recipient_type": "signer", "recipient_key": "client", "detail": "Permanent/General, diagnostic code: smtp; 550 5.1.1 As requested: user unknown" } } ``` ## recipient.failed Fires when an error prevents the invitation from being sent to a recipient. The recipient status changes to `failed`. The `data.detail` property contains a description of the failure, such as the recipient's email being on a blocklist. You may need to use the Replace Recipient (/docs/api/resources/recipients/replace) endpoint to assign a different person. ```json JSON { "id": "evt_7g8h9i0j1k2l3m4n5o6p", "type": "recipient.failed", "timestamp": "2025-12-31T23:59:59.999Z", "data": { "object_id": "re_00ZeZjRaXCgT30n1eBx53N", "object_type": "recipient", "envelope_id": "e387553d-cbb7-4924-abd8-b2d89699e9b5", "envelope_metadata": { "deal_id": "50055", "deal_owner": "Jane C." }, "recipient_type": "signer", "recipient_key": "client", "detail": "Recipient in email blocklist." } } ``` ## recipient.replaced Fires when a recipient is replaced through the Replace Recipient (/docs/api/resources/recipients/replace) endpoint. The original recipient's status changes to `replaced`. The `data` object includes `new_recipient_id` and `new_recipient_name` identifying the replacement recipient. ```json JSON { "id": "evt_8h9i0j1k2l3m4n5o6p7q", "type": "recipient.replaced", "timestamp": "2025-12-31T23:59:59.999Z", "data": { "object_id": "re_00ZeZjRaXCgT30n1eBx53N", "object_type": "recipient", "envelope_id": "e387553d-cbb7-4924-abd8-b2d89699e9b5", "envelope_metadata": { "deal_id": "50055", "deal_owner": "Jane C." }, "recipient_type": "signer", "recipient_key": "client", "new_recipient_id": "re_5SfFjI3eVfDokAXXDSjJlz", "new_recipient_name": "John Doe" } } ``` ## recipient.resent Fires when the invitation email is resent to a recipient via the Resend Request (/docs/api/resources/recipients/resend) endpoint. The recipient status remains `sent`. ```json JSON { "id": "evt_9i0j1k2l3m4n5o6p7q8r", "type": "recipient.resent", "timestamp": "2025-12-31T23:59:59.999Z", "data": { "object_id": "re_00ZeZjRaXCgT30n1eBx53N", "object_type": "recipient", "envelope_id": "e387553d-cbb7-4924-abd8-b2d89699e9b5", "envelope_metadata": { "deal_id": "50055", "deal_owner": "Jane C." }, "recipient_type": "signer", "recipient_key": "client" } } ``` ## Deliverable events URL: https://signatureapi.com/docs/api/resources/events/deliverable-events Description: Receive notifications when signed documents are generated and ready for download. Deliverable events notify you when SignatureAPI generates the final signed document (the deliverable), or when generation fails. This page explains each event type, when it fires, and the additional data included in the payload. ## deliverable.generated Fires when a deliverable is successfully generated and ready for download. The `data.url` property contains a pre-signed download link. This URL expires after 1 hour. If it has expired, call the Retrieve Deliverable (/docs/api/resources/deliverables/get) endpoint to get a fresh link. ```json JSON { "id": "evt_1a2b3c4d5e6f7g8h9i0j", "type": "deliverable.generated", "timestamp": "2025-12-31T23:59:59.999Z", "data": { "object_id": "del_00ZeZjRaXCgT30n1eBx53N", "object_type": "deliverable", "envelope_id": "e387553d-cbb7-4924-abd8-b2d89699e9b5", "envelope_metadata": { "deal_id": "50055", "deal_owner": "Jane C." }, "deliverable_type": "standard", "deliverable_name": null, "included_documents": ["contract", "addendum"], "url": "https://vault.signatureapi.com/envelopes/e387553d-cbb7-4924-abd8-b2d89699e9b5/deliverables/del_00ZeZjRaXCgT30n1eBx53N/sealed.pdf?Signature=..." } } ``` ## deliverable.failed Fires when deliverable generation fails. The deliverable status is set to `failed`. The `data.detail` property contains a human-readable explanation of the failure. Deliverable failures are rare. SignatureAPI support is notified automatically when this event fires. ```json JSON { "id": "evt_2b3c4d5e6f7g8h9i0j1k", "type": "deliverable.failed", "timestamp": "2025-12-31T23:59:59.999Z", "data": { "object_id": "del_00ZeZjRaXCgT30n1eBx53N", "object_type": "deliverable", "envelope_id": "e387553d-cbb7-4924-abd8-b2d89699e9b5", "envelope_metadata": { "deal_id": "50055", "deal_owner": "Jane C." }, "deliverable_type": "standard", "deliverable_name": null, "included_documents": ["contract", "addendum"], "detail": "The audit log could not be generated due to a system error." } } ``` ## Sender events URL: https://signatureapi.com/docs/api/resources/events/sender-events Description: Track sender email verification lifecycle events including creation, verification, failure, and deletion Sender events track the lifecycle of email address verification for senders. Each event includes a `data` object with the sender's `object_id` and `email`. ## Event types | Event | When it fires | |---|---| | `sender.created` | A sender was created and the verification email was sent | | `sender.verified` | The address owner completed email verification | | `sender.failed` | Verification failed due to a bounce or error | | `sender.deleted` | A sender was deleted from the account | --- ## sender.created Fires when a new sender is created and the verification email is sent. The sender starts in `pending_verification` status. Listen for `sender.verified` or `sender.failed` to track the verification outcome. ```json JSON { "id": "evt_yA80uuM4c90EbmxFuOC8Xv5", "type": "sender.created", "timestamp": "2025-01-01T00:00:00.000Z", "data": { "object_type": "sender", "object_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "email": "jennifer@example.com" } } ``` --- ## sender.verified Fires when a sender completes email verification. The sender status is now `verified`. SignatureAPI can send signing requests on behalf of this address. ```json JSON { "id": "evt_yA80uuM4c90EbmxFuOC8Xv5", "type": "sender.verified", "timestamp": "2025-01-01T00:00:00.000Z", "data": { "object_type": "sender", "object_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "email": "jennifer@example.com" } } ``` --- ## sender.failed Fires when sender email verification fails. This can happen due to a soft or hard bounce of the verification email, or an internal error. The `data.detail` property contains a human-readable explanation of the failure reason. ```json JSON { "id": "evt_yA80uuM4c90EbmxFuOC8Xv5", "type": "sender.failed", "timestamp": "2025-01-01T00:00:00.000Z", "data": { "object_type": "sender", "object_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "email": "jennifer@example.com", "detail": "Verification email bounced" } } ``` --- ## sender.deleted Fires when a sender is deleted from the account. SignatureAPI can no longer send signing requests on behalf of this address. ```json JSON { "id": "evt_yA80uuM4c90EbmxFuOC8Xv5", "type": "sender.deleted", "timestamp": "2025-01-01T00:00:00.000Z", "data": { "object_type": "sender", "object_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "email": "jennifer@example.com" } } ``` ## List events URL: https://signatureapi.com/docs/api/resources/events/all Description: Returns all events across your account, sorted with the most recent first. Returns a list of all events across your account. Events are sorted by timestamp, with the most recent appearing first. Results include envelope, recipient, deliverable, and sender events. ### Query parameters Filter by event type. For example, `envelope.completed` or `recipient.hard_bounced`. For the full list of event types, see: - Envelope Events (/docs/api/resources/events/envelope-events) - Recipient Events (/docs/api/resources/events/recipient-events) - Deliverable Events (/docs/api/resources/events/deliverable-events) - Sender Events (/docs/api/resources/events/sender-events) The maximum number of objects to return. Minimum is `1`, maximum is `20`. Defaults to `20`. ### Returns Returns a `200 OK` status with a paginated (/docs/api/pagination) list of event objects (/docs/api/resources/events/object) on success, or an error (/docs/api/errors) otherwise. ```json // GET https://api.signatureapi.com/v1/events // X-API-Key: key_test_... ``` ```json // HTTP/1.1 200 OK { "links": { "next": "https://api.signatureapi.com/v1/events?cursor=seq_0iuY6H...", "previous": "https://api.signatureapi.com/v1/events?cursor=seq_87unYn..." }, "data": [ { "id": "evt_45b62ui33fCihBWpW2kWDa", "type": "envelope.completed", "timestamp": "2025-12-31T23:59:00.000Z", "data": { "object_id": "2dc5d4bb-5f4e-41a8-aea8-077a48587e31", "object_type": "envelope", "envelope_id": "2dc5d4bb-5f4e-41a8-aea8-077a48587e31", "envelope_metadata": {} } }, { "id": "evt_7BFIYuMgWzJ1AHscS0RNxC", "type": "recipient.completed", "timestamp": "2025-12-31T23:58:59.000Z", "data": { "object_id": "re_00ZeZjRaXCgT30n1eBx53N", "object_type": "recipient", "envelope_id": "2dc5d4bb-5f4e-41a8-aea8-077a48587e31", "envelope_metadata": {}, "recipient_type": "signer", "recipient_key": "client", "session_id": "ses_2X6eHBCL84MDGrLQX0mHI72" } }, //... ] } ``` ## List envelope events URL: https://signatureapi.com/docs/api/resources/events/envelope Description: Returns all events for a specific envelope, sorted with the most recent first. Returns a list of events for a specific envelope. Events are sorted by timestamp, with the most recent appearing first. Results include envelope events, recipient events, and deliverable events associated with that envelope. ### Path parameters The unique identifier of the envelope. ### Query parameters Filter by event type. For example, `envelope.completed` or `recipient.sent`. For the full list of event types available when listing envelope events, see: - Envelope Events (/docs/api/resources/events/envelope-events) - Recipient Events (/docs/api/resources/events/recipient-events) - Deliverable Events (/docs/api/resources/events/deliverable-events) The maximum number of objects to return. Minimum is `1`, maximum is `20`. Defaults to `20`. ### Returns Returns a `200 OK` status with a paginated (/docs/api/pagination) list of event objects (/docs/api/resources/events/object) on success, or an error (/docs/api/errors) otherwise. ```json // GET https://api.signatureapi.com/v1/envelopes/2dc5d4bb-5f4e-41a8-aea8-077a48587e31/events // X-API-Key: key_test_... ``` ```json // HTTP/1.1 200 OK { "links": { "next": "https://api.signatureapi.com/v1/envelopes/2dc5d4bb-5f4e-41a8-aea8-077a48587e31/events?cursor=seq_0iuY6H...", "previous": "https://api.signatureapi.com/v1/envelopes/2dc5d4bb-5f4e-41a8-aea8-077a48587e31/events?cursor=seq_87unYn..." }, "data": [ { "id": "evt_45b62ui33fCihBWpW2kWDa", "type": "envelope.completed", "timestamp": "2025-12-31T23:59:00.000Z", "data": { "object_id": "2dc5d4bb-5f4e-41a8-aea8-077a48587e31", "object_type": "envelope", "envelope_id": "2dc5d4bb-5f4e-41a8-aea8-077a48587e31", "envelope_metadata": {} } }, { "id": "evt_7BFIYuMgWzJ1AHscS0RNxC", "type": "recipient.completed", "timestamp": "2025-12-31T23:58:59.000Z", "data": { "object_id": "re_00ZeZjRaXCgT30n1eBx53N", "object_type": "recipient", "envelope_id": "2dc5d4bb-5f4e-41a8-aea8-077a48587e31", "envelope_metadata": {}, "recipient_type": "signer", "recipient_key": "client", "session_id": "ses_2X6eHBCL84MDGrLQX0mHI72" } }, //... ] } ``` ## List recipient events URL: https://signatureapi.com/docs/api/resources/events/recipient Description: Returns all events for a specific recipient, sorted with the most recent first. Returns a list of events for a specific recipient. Events are sorted by timestamp, with the most recent appearing first. Results include only recipient events, such as delivery, signing, and bounce events. ### Path parameters The unique identifier of the recipient. ### Query parameters Filter by event type. For example, `recipient.completed` or `recipient.sent`. For the full list of event types available when listing recipient events, see Recipient Events (/docs/api/resources/events/recipient-events). The maximum number of objects to return. Minimum is `1`, maximum is `20`. Defaults to `20`. ### Returns Returns a `200 OK` status with a paginated (/docs/api/pagination) list of event objects (/docs/api/resources/events/object) on success, or an error (/docs/api/errors) otherwise. ```json // GET https://api.signatureapi.com/v1/recipients/re_00ZeZjRaXCgT30n1eBx53N/events // X-API-Key: key_test_... ``` ```json // HTTP/1.1 200 OK { "links": { "next": "https://api.signatureapi.com/v1/recipients/re_00ZeZjRaXCgT30n1eBx53N/events?cursor=seq_0iuY6H...", "previous": "https://api.signatureapi.com/v1/recipients/re_00ZeZjRaXCgT30n1eBx53N/events?cursor=seq_87unYn..." }, "data": [ { "id": "evt_45b62ui33fCihBWpW2kWDa", "type": "recipient.completed", "timestamp": "2025-12-31T23:58:00.000Z", "data": { "object_id": "re_00ZeZjRaXCgT30n1eBx53N", "object_type": "recipient", "envelope_id": "2dc5d4bb-5f4e-41a8-aea8-077a48587e31", "envelope_metadata": {}, "recipient_type": "signer", "recipient_key": "client", "session_id": "ses_2X6eHBCL84MDGrLQX0mHI72" } }, { "id": "evt_7BFIYuMgWzJ1AHscS0RNxC", "type": "recipient.sent", "timestamp": "2025-12-31T23:50:00.000Z", "data": { "object_id": "re_00ZeZjRaXCgT30n1eBx53N", "object_type": "recipient", "envelope_id": "2dc5d4bb-5f4e-41a8-aea8-077a48587e31", "envelope_metadata": {}, "recipient_type": "signer", "recipient_key": "client" } }, //... ] } ``` ## Upload URL: https://signatureapi.com/docs/api/resources/uploads/object Description: Store PDF, DOCX, or PNG files in SignatureAPI and reference them as document sources in envelopes. An upload is a file stored in SignatureAPI. You can use an upload as the source file for a document in an envelope. Uploads are the simplest way to supply document files when you do not want to host them yourself. After uploading a file, pass the returned `url` value as the `url` property of a document (/docs/api/resources/documents/object). The following file formats are supported: | Format | Media Type | |--------|------------| | PDF | `application/pdf` | | DOCX | `application/vnd.openxmlformats-officedocument.wordprocessingml.document` | | PNG | `image/png` | ## Retention Uploads have one of two retention types, indicated by the `retention` property: | Retention | Description | |-----------|-------------| | Temporary | Created through the API. Automatically deleted 24 hours after creation. Use this for one-time document sends. | | Permanent | Stored indefinitely and reusable across multiple envelopes. Identified by a unique `key`. Created by storing an upload (/docs/api/resources/uploads/store) through the API or uploading through the Library (https://dashboard.signatureapi.com/library) in your dashboard. | The Upload resource replaces the File resource (/docs/api/resources/files/object). The File resource is soft-deprecated but remains available for backward compatibility. ## Attributes The unique identifier of the upload. The retention type of the upload. | Value | Description | |-------|-------------| | `temporary` | The file is automatically deleted 24 hours after creation. | | `permanent` | The file is stored indefinitely. Created by storing an upload (/docs/api/resources/uploads/store) or through the dashboard library. | A unique identifier for the upload within your account. Present only on permanent uploads (`retention` is `permanent`). Only lowercase letters, numbers, hyphens, and underscores are allowed. Maximum 100 characters. The internal URL used to reference this upload in other API calls, such as `document.url`. You cannot use this URL to download the file directly. The file format of the upload. | Value | Description | |-------|-------------| | `pdf` | A PDF file (`application/pdf`). | | `docx` | A DOCX file (`application/vnd.openxmlformats-officedocument.wordprocessingml.document`). | | `png` | A PNG image (`image/png`). | The SHA-256 hash of the uploaded file, in hexadecimal format. The size of the uploaded file in bytes. Maximum 5 MB; see Create Upload (/docs/api/resources/uploads/create) for size recommendations. The date and time when the upload was created, in ISO 8601 format. The date and time when the upload will be automatically deleted, in ISO 8601 format. Present only on temporary uploads (`retention` is `temporary`). The expiration is 24 hours after creation. ```json Temporary upload { "id": "upl_1sAAaVfabdt0esVjmSTmLA", "retention": "temporary", "url": "https://api.signatureapi.com/v1/uploads/upl_1sAAaVfabdt0esVjmSTmLA", "format": "pdf", "sha_256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef", "size": 102400, "created_at": "2025-12-30T12:00:00.000Z", "expires_at": "2025-12-31T12:00:00.000Z" } ``` ```json Permanent upload { "id": "upl_3joO7lxE8HVhOZmkCHFCxK", "retention": "permanent", "key": "contract-template-v2", "url": "https://api.signatureapi.com/v1/uploads/upl_3joO7lxE8HVhOZmkCHFCxK", "format": "docx", "sha_256": "abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789", "size": 234567, "created_at": "2025-12-30T12:00:00.000Z" } ``` ## Create an upload URL: https://signatureapi.com/docs/api/resources/uploads/create Description: Upload a PDF, DOCX, or PNG file to SignatureAPI and get back a URL to use as a document source. Upload a file to SignatureAPI for use as a document source in an envelope. Send the raw file bytes in the request body with the appropriate `Content-Type` header. The response includes a `url` property. Pass this value as the `url` property of a document (/docs/api/resources/documents/object) when creating an envelope: ```json // POST https://api.signatureapi.com/v1/envelopes // X-API-Key: key_test_... // Content-Type: application/json { "documents": [ { "url": "https://api.signatureapi.com/v1/uploads/upl_1sAAaVfabdt0esVjmSTmLA", //... } ], //... } ``` Uploads created through this endpoint are temporary and expire 24 hours after creation. To store a file permanently for reuse across multiple envelopes, use the Store Upload (/docs/api/resources/uploads/store) endpoint or upload it to your Library (https://dashboard.signatureapi.com/library) in the dashboard. The Create Upload endpoint replaces the Create File endpoint (/docs/api/resources/files/create). The File resource is soft-deprecated but remains available for backward compatibility. ## Request Send the raw file bytes as the request body. Set the `Content-Type` header to match the file format. | Content-Type | Format | |--------------|--------| | `application/pdf` | `pdf` | | `application/vnd.openxmlformats-officedocument.wordprocessingml.document` | `docx` | | `image/png` | `png` | Maximum file size: 5 MB. For reliable uploads, we recommend keeping files at or below 4.4 MB. Files between 4.4 MB and 5 MB may still succeed, but can be rejected depending on how they encode internally. If you need to use larger files, host them on your own storage and pass the public URL as the `url` property of a document (/docs/api/resources/documents/object) when creating an envelope, or use the legacy Files API (/docs/api/resources/files/create). ```bash cURL curl -X POST https://api.signatureapi.com/v1/uploads \ --data-binary "@/path/to/file.pdf" \ -H "Content-Type: application/pdf" \ -H "X-API-Key: key_test_..." ``` ```typescript TypeScript async function uploadPdf() { const fileStream = fs.createReadStream("/path/to/file.pdf"); const response = await axios.post( "https://api.signatureapi.com/v1/uploads", fileStream, { headers: { "Content-Type": "application/pdf", "X-API-Key": "key_test_..." }, } ); console.log("Upload successful:", response.data); } uploadPdf(); ``` ```python Python with open("/path/to/file.pdf", "rb") as f: response = requests.post( "https://api.signatureapi.com/v1/uploads", headers={ "Content-Type": "application/pdf", "X-API-Key": "key_test_..." }, data=f ) print(response.json()) ``` ```ruby Ruby require "net/http" require "uri" uri = URI("https://api.signatureapi.com/v1/uploads") File.open("/path/to/file.pdf", "rb") do |file| request = Net::HTTP::Post.new(uri) request["Content-Type"] = "application/pdf" request["X-API-Key"] = "key_test_..." request.body = file.read response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end puts response.body end ``` ```csharp C# using System.Net.Http; using System.Net.Http.Headers; using var client = new HttpClient(); using var fileStream = File.OpenRead("/path/to/file.pdf"); var request = new HttpRequestMessage(HttpMethod.Post, "https://api.signatureapi.com/v1/uploads") { Content = new StreamContent(fileStream) }; request.Content.Headers.ContentType = new MediaTypeHeaderValue("application/pdf"); request.Headers.Add("X-API-Key", "key_test_..."); var response = await client.SendAsync(request); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ```java Java var client = HttpClient.newHttpClient(); var request = HttpRequest.newBuilder() .uri(URI.create("https://api.signatureapi.com/v1/uploads")) .header("Content-Type", "application/pdf") .header("X-API-Key", "key_test_...") .POST(HttpRequest.BodyPublishers.ofFile(Path.of("/path/to/file.pdf"))) .build(); var response = client.send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.body()); ``` ```go Go package main "bytes" "fmt" "io" "net/http" "os" ) func main() { file, err := os.Open("/path/to/file.pdf") if err != nil { panic(err) } defer file.Close() data, err := io.ReadAll(file) if err != nil { panic(err) } req, err := http.NewRequest("POST", "https://api.signatureapi.com/v1/uploads", bytes.NewReader(data)) if err != nil { panic(err) } req.Header.Set("Content-Type", "application/pdf") req.Header.Set("X-API-Key", "key_test_...") client := &http.Client{} resp, err := client.Do(req) if err != nil { panic(err) } defer resp.Body.Close() body, _ := io.ReadAll(resp.Body) fmt.Println(string(body)) } ``` File uploads must be made from your server, not from the browser. The API requires your API key in the request header, which must never be exposed to the client. If you need to accept files from users in the browser, upload the file to your own server first, then forward it to the SignatureAPI uploads endpoint. ## Returns Returns a `201 Created` status code and an upload object (/docs/api/resources/uploads/object) on success, or an error (/docs/api/errors) otherwise. ```json // POST https://api.signatureapi.com/v1/uploads // X-API-Key: key_test_... // Content-Type: application/pdf // ``` ```json PDF upload // HTTP/1.1 201 Created { "id": "upl_1sAAaVfabdt0esVjmSTmLA", "retention": "temporary", "url": "https://api.signatureapi.com/v1/uploads/upl_1sAAaVfabdt0esVjmSTmLA", "format": "pdf", "sha_256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef", "size": 102400, "created_at": "2025-12-30T12:00:00.000Z", "expires_at": "2025-12-31T12:00:00.000Z" } ``` ```json DOCX upload // HTTP/1.1 201 Created { "id": "upl_3joO7lxE8HVhOZmkCHFCxK", "retention": "temporary", "url": "https://api.signatureapi.com/v1/uploads/upl_3joO7lxE8HVhOZmkCHFCxK", "format": "docx", "sha_256": "abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789", "size": 234567, "created_at": "2025-12-30T12:00:00.000Z", "expires_at": "2025-12-31T12:00:00.000Z" } ``` ```json PNG upload // HTTP/1.1 201 Created { "id": "upl_7kBBcD2eF3gHiJkLmNoPqR", "retention": "temporary", "url": "https://api.signatureapi.com/v1/uploads/upl_7kBBcD2eF3gHiJkLmNoPqR", "format": "png", "sha_256": "fedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210", "size": 51200, "created_at": "2025-12-30T12:00:00.000Z", "expires_at": "2025-12-31T12:00:00.000Z" } ``` ## Store an upload URL: https://signatureapi.com/docs/api/resources/uploads/store Description: Convert a temporary upload into a permanent upload that does not expire. Convert a temporary upload into a permanent upload. The file is moved to permanent storage and no longer expires. A unique `key` is required to identify the permanent upload. Use this endpoint when you want to reuse a file across multiple envelopes without re-uploading it each time. For example, store a company logo or a contract template that you reference repeatedly. Once stored, the upload's `retention` changes from `temporary` to `permanent` and the `expires_at` property is removed. The upload `id` and `url` remain the same. ## Path Parameters The unique identifier of the upload to store. ## Body Parameters #### `key` (string) A unique identifier for the upload within your account. Only lowercase letters, numbers, hyphens, and underscores are allowed. Maximum 100 characters. ```json // POST https://api.signatureapi.com/v1/uploads/{upload_id}/store // X-API-Key: key_test_... // Content-Type: application/json { "key": "acme-logo" } ``` ## Returns Returns a `200 OK` status code and an upload object (/docs/api/resources/uploads/object) with `retention` set to `permanent`, or an error (/docs/api/errors) otherwise. ```json Request // POST https://api.signatureapi.com/v1/uploads/{upload_id}/store // X-API-Key: key_test_... // Content-Type: application/json { "key": "contract-template-v2" } ``` ```json Response // HTTP/1.1 200 OK { "id": "upl_1sAAaVfabdt0esVjmSTmLA", "retention": "permanent", "key": "contract-template-v2", "url": "https://api.signatureapi.com/v1/uploads/upl_1sAAaVfabdt0esVjmSTmLA", "format": "pdf", "sha_256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef", "size": 102400, "created_at": "2025-12-30T12:00:00.000Z" } ``` ## Retrieve an upload URL: https://signatureapi.com/docs/api/resources/uploads/get Description: Retrieve the metadata for an existing upload by its ID. Retrieve the metadata for an existing upload. The response includes the file format, size, SHA-256 hash, retention type, and creation time. This endpoint returns upload metadata only. You cannot download the file content through the API. The Retrieve Upload endpoint replaces the Get File endpoint (/docs/api/resources/files/get). The File resource is soft-deprecated but remains available for backward compatibility. ## Path Parameters The unique identifier of the upload. ## Returns Returns a `200 OK` status code and an upload object (/docs/api/resources/uploads/object) on success, or an error (/docs/api/errors) otherwise. ```json // GET https://api.signatureapi.com/v1/uploads/{upload_id} // X-API-Key: key_test_... ``` ```json Temporary Upload // HTTP/1.1 200 OK { "id": "upl_1sAAaVfabdt0esVjmSTmLA", "retention": "temporary", "url": "https://api.signatureapi.com/v1/uploads/upl_1sAAaVfabdt0esVjmSTmLA", "format": "pdf", "sha_256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef", "size": 102400, "created_at": "2025-12-30T12:00:00.000Z", "expires_at": "2025-12-31T12:00:00.000Z" } ``` ```json Permanent Upload // HTTP/1.1 200 OK { "id": "upl_3joO7lxE8HVhOZmkCHFCxK", "retention": "permanent", "key": "contract-template-v2", "url": "https://api.signatureapi.com/v1/uploads/upl_3joO7lxE8HVhOZmkCHFCxK", "format": "docx", "sha_256": "abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789", "size": 234567, "created_at": "2025-12-30T12:00:00.000Z" } ``` ## Sender URL: https://signatureapi.com/docs/api/resources/senders/object Description: A sender is a verified email address that SignatureAPI uses when sending signing requests to recipients A sender is a verified email address. SignatureAPI sends signing request emails to recipients on behalf of the sender's address. The sender's name, email address, and organization appear in every email sent to recipients, and the sender's address is used as the Reply-To address. Before an email address can be used as a sender, the address owner must complete email verification. SignatureAPI initiates this by sending a verification email when you create the sender. Image: (/docs/images/sender-1.png) ## Verification lifecycle A sender goes through a verification process before it can be used. See the sender lifecycle (/docs/api/resources/senders/lifecycle) for details. ## Managing senders You can manage senders in the Dashboard (https://dashboard.signatureapi.com/settings/senders) under Settings, or programmatically using the API. Sender management via API is currently in public preview. To enable it, contact support (/support). **Dashboard.** When you created your SignatureAPI account, a sender was automatically added using your account email address. That sender is already verified. To add a new sender, click **New Sender** in the Senders settings and enter the email address to verify. **API.** Create a sender using the Create a sender (/docs/api/resources/senders/create) endpoint. SignatureAPI sends the verification email automatically. Listen for the `sender.verified` (/docs/api/resources/events/sender-events#sender.verified) or `sender.failed` (/docs/api/resources/events/sender-events#sender.failed) webhook events to track the outcome. ## Default sender Every account has a default sender. When you create an envelope without specifying a sender, SignatureAPI uses the default sender's name and email. To change your account's default sender, click **Set default** next to the desired sender in the Dashboard. To specify a sender explicitly on an envelope, include the `sender` property in the request body: ```json // POST https://api.signatureapi.com/v1/envelopes // X-API-Key: key_test_... // Content-Type: application/json { "title": "Consulting Agreement", //... "sender": { "name": "Jennifer Lee", "email": "jennifer@example.com", "organization": "Acme Enterprises" } } ``` ## Email addresses in signing requests All signing request emails are sent from `noreply@signatureapi.com`. This cannot be changed. SignatureAPI enforces a strict DMARC policy to protect email deliverability across major email providers. Sending from custom domains would risk emails landing in spam or being rejected. Your verified sender address appears as the **Reply-To** address, so recipient replies go directly to you. The sender's name and organization also appear in the email body. To control the Reply-To address and sender details, create and verify a sender (#managing-senders) with the desired email address, then assign it to envelopes or set it as your default sender (#default-sender) or in the envelope request. Sending from a custom domain is available exclusively as part of the branding package for enterprise customers with very high monthly volumes. Set the From address using the `envelope.branding.email.from` (/docs/api/resources/envelopes/object#param-from) property. Contact support (/support) to discuss eligibility. However, consider this could affect email deliverability and it's exclusive to premium enterprise customers. ## Attributes The unique identifier of the sender. The email address of the sender. SignatureAPI sends signing request emails to recipients on behalf of this address. The current verification status of the sender. | Status | Description | |--------|-------------| | `pending_verification` | A verification email was sent. The address owner has not yet confirmed. | | `verified` | The address owner confirmed the verification email. This sender can be used on envelopes. | | `failed` | Verification failed due to a bounce or error. This sender cannot be used. | The time at which the sender was created, formatted as an ISO 8601 timestamp. ```json Example Sender { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "email": "jennifer@example.com", "status": "verified", "created_at": "2025-01-01T00:00:00.000Z" } ``` ## Sender Lifecycle URL: https://signatureapi.com/docs/api/resources/senders/lifecycle Description: The verification lifecycle of a sender. When you create a sender, it starts in `pending_verification` status. SignatureAPI sends a verification email to the address. Once the address owner clicks the confirmation link, the status changes to `verified`. If the verification email bounces or an error occurs, the status changes to `failed`. Only senders with `verified` status can be assigned to envelopes. | Status | Description | |--------|-------------| | `pending_verification` | A verification email was sent. The address owner has not yet confirmed. | | `verified` | The address owner confirmed the verification email. This sender can be used on envelopes. | | `failed` | Verification failed due to a bounce or error. This sender cannot be used. | Subscribe to `sender.verified` (/docs/api/resources/events/sender-events#sender-verified) or `sender.failed` (/docs/api/resources/events/sender-events#sender-failed) webhook events to track the outcome. ## Create a sender URL: https://signatureapi.com/docs/api/resources/senders/create Description: Register a new sender email address and start the verification process Sender management via API is currently in public preview. To enable it, contact support (/support). Registers a new sender email address and starts the verification process. SignatureAPI sends a verification email to the provided address. The sender is returned with `pending_verification` status. Once the address owner clicks the confirmation link, the sender status changes to `verified`. The sender can then be used on envelopes. Listen for the `sender.verified` (/docs/api/resources/events/sender-events#sender.verified) or `sender.failed` (/docs/api/resources/events/sender-events#sender.failed) webhook events to track the outcome. ## Body parameters #### `email` (string) The email address to register as a sender. Must be a valid email address. Maximum 320 characters. ## Returns Returns a `201 Created` status code and a sender object (/docs/api/resources/senders/object) on success, or an error (/docs/api/errors) otherwise. ```json // POST https://api.signatureapi.com/v1/senders // X-API-Key: key_test_... // Content-Type: application/json { "email": "jennifer@example.com" } ``` ```json Response // HTTP/1.1 201 Created { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "email": "jennifer@example.com", "status": "pending_verification", "created_at": "2025-01-01T00:00:00.000Z" } ``` ## Get a sender URL: https://signatureapi.com/docs/api/resources/senders/get Description: Retrieve the details and current verification status of a sender Sender management via API is currently in public preview. To enable it, contact support (/support). Retrieves the details of a sender (/docs/api/resources/senders/object). Use this endpoint to check the current verification status of a sender after creation. ## Path parameters The unique identifier of the sender. ## Returns Returns a `200 OK` status code and a sender object (/docs/api/resources/senders/object) on success, or an error (/docs/api/errors) otherwise. ```json // GET https://api.signatureapi.com/v1/senders/a1b2c3d4-e5f6-7890-abcd-ef1234567890 // X-API-Key: key_test_... ``` ```json Response // HTTP/1.1 200 OK { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "email": "jennifer@example.com", "status": "verified", "created_at": "2025-01-01T00:00:00.000Z" } ``` ## Delete a sender URL: https://signatureapi.com/docs/api/resources/senders/delete Description: Remove a sender email address from your account Sender management via API is currently in public preview. To enable it, contact support (/support). Deletes a sender (/docs/api/resources/senders/object). Once deleted, the email address can no longer be used on new envelopes. Envelopes already sent using this sender are not affected. ## Path parameters The unique identifier of the sender. ## Returns Returns a `204 No Content` status code on success, or an error (/docs/api/errors) otherwise. ```json // DELETE https://api.signatureapi.com/v1/senders/a1b2c3d4-e5f6-7890-abcd-ef1234567890 // X-API-Key: key_test_... ``` ```json Response // HTTP/1.1 204 Empty ``` ## API Guides URL: https://signatureapi.com/docs/api/guides/overview Description: Step-by-step tutorials and how-to guides for implementing common SignatureAPI workflows ## How-Tos The How-To guides contain practical, step-by-step instructions to help you quickly complete specific tasks using SignatureAPI. ### Signature Positioning ### Placeholders Link: /docs/api/guides/how-to/use-placeholders Position a signature (or any other place) using a placeholder within the document. ### Fixed Positions Link: /docs/api/guides/how-to/use-fixed-positions Position a signature (or any other place) using fixed positions (coordinates). ### Signing Order ### Parallel Signing Link: /docs/api/guides/how-to/parallel-signing How to send an envelope for signatures to multiple recipients in parallel. ### Sequential Signing Link: /docs/api/guides/how-to/sequential-signing How to send an envelope for signatures to multiple recipients signing in order. ### Recipients ### Send to an Approver Link: /docs/api/guides/how-to/send-to-approver Add an approver who reviews and approves a document before the signer signs it. ### Prepare a Document Before Sending to Sign Link: /docs/api/guides/how-to/prepare-before-signing Have a preparer fill in fields before the signer receives the envelope. ### Use Custom Authentication Link: /docs/api/guides/how-to/custom-authentication Control access to signing ceremonies using your own authentication system. ### Documents & Templates ### Use Document Templates Link: /docs/api/guides/how-to/document-templates Generate documents from DOCX templates with dynamic data, conditionals, and merge fields. ### Ceremonies ### Embed Signing in a Web App Link: /docs/api/guides/how-to/embed-web Embed the signing ceremony in a web application using an iframe. ### Embed Signing in a Mobile App Link: /docs/api/guides/how-to/embed-mobile Embed the signing ceremony in a mobile app using WebView. ### Webhooks ### Set Up Webhooks Link: /docs/api/guides/how-to/set-up-webhooks Receive real-time notifications when envelope events happen. ### Envelope Management ### Customize Branding Link: /docs/api/guides/how-to/customize-branding Add your logo, brand colors, and email footer to envelopes. ### Organize with Topics and Metadata Link: /docs/api/guides/how-to/organize-topics-metadata Tag envelopes with topics and attach custom metadata for organization and integration. ## Quickstart URL: https://signatureapi.com/docs/api/guides/quickstart Description: Send your first document for signature using the SignatureAPI in this step-by-step tutorial ## Introduction In this quickstart, we'll walk you through sending a simple privacy policy document to Jane Doe (at jane​@​example.com) for her signature. ## Get your API key To get started, sign up (https://accounts.signatureapi.com/sign-up) for a free test API key (/docs/api/authentication). This test API key allows you to create test envelopes (/docs/api/test-mode) without any legal effect and at no cost. ## Create your first envelope An envelope (/docs/api/resources/envelopes/object) is a container that holds the documents you need to send for signing. Each envelope can include one or more documents and can be sent to one or multiple signers. In this quickstart, we will create an envelope with one document, one recipient, and a single signing place. We’ll use `curl` and the command line for this example. Replace `key_test_xxxxxxxx` in the code snippet below with your test API key (which starts with `key_test_`) and paste it into your command line. ```bash curl -X POST \ -H 'Content-Type: application/json' \ -H 'X-API-Key: key_test_xxxxxxxx' \ -d '{ "title": "Dummy Consent", "message": "Please review and sign the attached Dummy Privacy Policy for internal testing purposes. This document is not legally binding and is used solely for demonstration\n\nThank you for your cooperation.", "documents": [ { "url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/privacy-placeholder.pdf", "places": [ { "key": "signer_signs_here", "type": "signature", "recipient_key": "visitor" } ] } ], "recipients": [ { "key": "visitor", "type": "signer", "name": "Jane Doe", "email": "jane@example.com" } ] }' \ https://api.signatureapi.com/v1/envelopes ``` This request creates an envelope titled `Dummy Consent` with a message `"Please review..."` that will be included in the emails sent to the recipient. The envelope has one recipient, identified by the key `visitor`. This recipient is a signer named `Jane Doe`, with the email `jane@example.com`. The envelope contains one document, a PDF hosted at `https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/privacy-placeholder.pdf`. The document includes a place for the recipient `visitor` to sign. The placeholder is of type `signature` and links to the placeholder `[[signer_signs_here]]` inside the PDF document. Once you've sent the request, you should see a response like this (formatted for readability): ```json { "id": "69b50512-a771-4bdf-5555-12c555590aa2", "title": "Dummy Consent", "label": null, "message": "Please review and sign the attached Dummy Privacy Policy for internal testing purposes. This document is not legally binding and is used solely for demonstration\n\nThank you for your cooperation.", "status": "processing", "language": "en", "timezone": "UTC", "timestamp_format": "MM/DD/YYYY hh:mm:ss", "mode": "test", "routing": "sequential", "deliverable": null, "topics": [], "metadata": {}, "sender": { "name": "Richard Roe", "email": "richard@example.com", "organization": null }, "documents": [ { "id": "doc_7C4In8kXXYYf4kfkiUce94", "envelope_id": "69b50512-a771-4bdf-5555-12c555590aa2", "title": null, "page_count": 2, "url": "https: //pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/privacy-placeholder.pdf", "format": "pdf", "data": null, "fixed_positions": [], "places": [ { "key": "signer_signs_here", "type": "signature", "recipient_key": "visitor" } ] } ], "recipients": [ { "id": "re_0RKFGQ8EgXXYYKq854c045", "envelope_id": "69b50512-a771-4bdf-5555-12c555590aa2", "type": "signer", "key": "visitor", "name": "Jane Doe", "email": "jane@example.com", "ceremony": { "authentication": [ { "type": "email_link", "subject_override": null, "message_override": null } ], "redirect_url": null, "redirect_delay": 3, "embeddable_in": [], "url_variant": "standard", "url": null }, "delivery_type": "email", "ceremony_creation": "automatic", "signature_options": ["typed", "drawn"], "status": "pending", "completed_at": null, "status_updated_at": "2025-12-31T23:59:59.000Z" } ], "created_at": "2025-12-31T23:59:59.000Z", "completed_at": null } ``` ## Check the sent email Although test API keys don't send real emails, you can view the email that would be sent in the Dashboard. 1. Log in to your Dashboard 2. Navigate to the **Envelopes** list and select your newly created envelope. Image: Select your envelope in the dashboard (/docs/images/quickstart-dashboard-envelopes.webp) In the envelope details, scroll down to the **Emails** section and click on the email sent to Jane Doe. Image: Display envelope (/docs/images/quickstart-dashboard-envelope.webp) You'll be able to preview the email and see how it would appear if it were sent to the recipient. In test mode, however, emails are not actually sent to recipients. Image: Display envelope (/docs/images/quickstart-dashboard-email.webp) Click on the blue button in the email preview to go to the signing ceremony as Jane. ## Sign the envelope as Jane Now, you'll step into Jane Doe’s shoes as the signer. Go through the signing ceremony and sign the document as Jane would. Image: Display envelope (/docs/images/quickstart-ceremony.webp) ## Check the envelope in the API Once Jane has signed the document, let’s check the status of the envelope and the recipients to make sure everything is moving along smoothly. To do this, we'll use the following curl command to retrieve the envelope’s status. Replace the API key with your test key and `00000000-0000-0000-0000-000000000000` with the envelope ID you received earlier. ```bash curl -X GET \ -H 'X-API-Key: key_test_xxxxxxxx' \ https://api.signatureapi.com/v1/envelopes/00000000-0000-0000-0000-000000000000 ``` The response will look something like this (we redacted some of the parts that didn't change): ```json { "id": "3cd512e8-0db8-4608-af95-bfcf9dd08620", "status": "completed", // ... "deliverable": { "id": "del_2gejfUSFk9H0dF20KklS2y", "envelope_id": "3cd512e8-0db8-4608-af95-bfcf9dd08620", "status": "processing", "type": "standard", "language": "en", "timezone": "UTC", "timestamp_format": "DD/MM/YYYY HH:mm:ss", "url": null }, // ... "recipients": [ { "id": "re_1RIbLpPWJL44QTBY6n8jBW", "envelope_id": "3cd512e8-0db8-4608-af95-bfcf9dd08620", "type": "signer", "key": "visitor", // ... "status": "completed", "completed_at": "2024-09-04T19:31:05.188Z", "status_updated_at": "2024-09-04T19:31:05.438Z" } ], "created_at": "2024-09-04T19:30:24.822Z", "completed_at": "2024-09-04T19:31:05.188Z" } ``` Here’s what to check: - **Recipient Status**: Inside the `recipients` array, the status should be marked as `completed`. This confirms Jane signed the document. - **Envelope Status**: The envelope (root) object's status should also be set to `completed`, meaning the envelope process is finished as all the recipients signed the envelope. - **Deliverable Status**: The deliverable object may initially show a `processing` status, which indicates SignatureAPI is still generating the final signed document. This can take up to two minutes. You can repeat the GET request to check when it's ready. Once completed, the deliverable status will change to `generated`: ```json { //... "deliverable": { "id": "del_2gejfUSFk9H0dF20KklS2y", "envelope_id": "3cd512e8-0db8-4608-af95-bfcf9dd08620", "status": "generated", "type": "standard", "language": "en", "timezone": "UTC", "timestamp_format": "DD/MM/YYYY HH:mm:ss", "url": "https://s3.us-east-2.amazonaws.com/signatureapi-vault/envelopes/3cd512e8-0db8-4608-af95-bfcf9dd08620/deliverables/del_2gejfUSFk9H0dF20KklS2y/sealed.pdf?..." }, //... } ``` ## Check the envelope in the dashboard The deliverable is also sent to the recipients. In this case, Jane. To view the email Jane received with the completed document, follow these steps: 1. Go to the envelope page in your Dashboard. 2. Verify that the envelope is marked as completed. 3. In the "Emails" section, you'll see all the emails related to this envelope. Look for the one sent to Jane titled: "Completed: Dummy Consent." Image: Display envelope (/docs/images/quickstart-dashboard-deliverable.webp) You’ll also notice that two additional notifications were sent to the account owner (Richard Roe). These notify you that Jane signed the envelope and that the envelope process is fully completed. From the envelope page, you can download the signed document (the deliverable) by clicking the download button. ## What's Next You’ve just scratched the surface of what SignatureAPI can do. Here are a few powerful features you can explore: - Add multiple documents (/docs/api/resources/documents/object) and recipients (/docs/api/resources/recipients/object) to a single envelope for more complex workflows. - Customize envelope branding (/docs/api/resources/envelopes/branding) with your company logo, colors, and email customizations for a professional experience. - Embed the signing interface (/docs/embedded/introduction) directly into your web or mobile application, giving users a seamless experience. - Generate documents from templates (/docs/api/resources/documents/templates) with customizable fields and conditional logic for dynamic document creation. - Upload documents and templates (/docs/api/resources/uploads/create) to SignatureAPI, so you don’t have to host them yourself. - Add signatures (/docs/api/resources/places/signature), dates (/docs/api/resources/places/date), or text fields to documents using either placeholders (/docs/api/resources/places/positioning#placeholders) or fixed positions (/docs/api/resources/places/positioning#fixed-positions) for precise placement. - Use webhooks (/docs/api/webhooks) to receive real-time notifications in your application when events happen. - Customize the language (/docs/api/resources/envelopes/language) of recipient interfaces and emails to match your audience. - Adjust the timestamp formats (/docs/api/resources/envelopes/timestamp-format) and time zones (/docs/api/resources/envelopes/timezone) to suit your location and preferences. ## Use Placeholders to Position Signatures URL: https://signatureapi.com/docs/api/guides/how-to/use-placeholders Description: Position signature fields dynamically using text placeholders embedded in your documents In SignatureAPI, places (/docs/api/resources/places/object) are areas in a document where recipients sign, enter information, or where details, such as dates, are automatically added. The signature place (/docs/api/resources/places/signature) is one of such places. There are two ways to position places: fixed positions (/docs/api/resources/places/signature#fixed-positions) (coordinates) and placeholders (/docs/api/resources/places/signature#placeholders) within the document. In this example, we will show how to position a **signature place** using a **placeholder**. For this example, we will create an envelope with: - One recipient (of type `signer`), identified with the key `visitor`. - The visitor signs a single PDF document. - The document will have one signature place, identified with the key `signer_signs_here`, that will be signed by the recipient `visitor`. All other envelope settings use the default configuration: - The recipient will receive an email with a link to sign. - The account's default language, timezone, and timestamp format used. ## Prepare your Document Placeholders are text within your PDF document that define the location where places (such as signatures, initials, text inputs, etc.) should appear. They follow the format `[[place_key]]`, where `place_key` identifies the place within the document. Place placeholders use double brackets: `[[place_key]]`. Template fields use double curly braces (`{{field_key}}`) to inject content into DOCX documents. A DOCX document can use both. See Document Templates (/docs/api/resources/documents/templates) for template fields. For this example, we prepared a document that contains the placeholder `[[signer_signs_here]]` to indicate the position of the place with the key `signer_signs_here`. ### Example document Link: https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/privacy-placeholder.pdf Download the PDF used in this example. In our document, the placeholder is highlighted in blue for visibility. However, we recommend setting it to white so it remains invisible to the signer. Image: (/docs/api/guides/how-to/images/use-placeholders-1.png) ## Create the Envelope When creating the envelope, add the signature place object to the `places` array inside the document object, with the following properties: - `key`: This identifies the place within the document. Must match what’s inside the square brackets in the placeholder inside the document file, in this case: `signer_signs_here`. - `type`: As this is a signature place, we use the value `signature`. - `recipient_key`: The key of the recipient that will sign in this place. In this example, there is just one recipient, who has the key `visitor`. ```json // POST https://api.signatureapi.com/v1/envelopes // X-Api-Key: { "title": "Dummy Consent", "message": "Please review and sign the Dummy Privacy Policy for internal testing purposes. This document is not legally binding and is used solely for demonstration\n\nThank you for your cooperation.", "documents": [ { "url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/privacy-placeholder.pdf", "places": [ { "key": "signer_signs_here", "type": "signature", "recipient_key": "visitor" } ] } ], "recipients": [ { "type": "signer", "key": "visitor", "name": "John Doe", "email": "john@example.com" } ] } ``` ## Result If the request is successful, SignatureAPI will send John Doe (the recipient) an email with a link to sign. John will click the link and will be able to place his signature on top of the signature line. Image: (/docs/api/guides/how-to/images/use-placeholders-2.png) ## Try It Try this example in Postman (/docs/api/postman) using your test API key (/docs/api/test-mode) to create a free, non-binding test envelope. Test envelopes won't send emails, but you can review them in your dashboard. ## Keep Learning - Learn how to position a signature using coordinates (/docs/api/guides/how-to/use-fixed-positions) when exact positioning is required. - Explore other types of places (/docs/api/resources/places/object), such as initials (/docs/api/resources/places/initials), text inputs (/docs/api/resources/places/text-input), or completion dates (/docs/api/resources/places/date). ## Use Fixed Positions to Position Signatures URL: https://signatureapi.com/docs/api/guides/how-to/use-fixed-positions Description: Position signature fields precisely using page coordinates for fixed-layout documents In SignatureAPI, places (/docs/api/resources/places/object) are areas in a document where recipients sign, enter information, or where details, such as dates, are automatically added. The signature place (/docs/api/resources/places/signature) is one of such places. There are two ways to position places: fixed positions (/docs/api/resources/places/signature#fixed-positions) (coordinates) and placeholders (/docs/api/resources/places/signature#placeholders) within the document. In this example, we will show how to position a **signature place** using **fixed positions**. For this example, we will create an envelope with: - One recipient (of type `signer`), identified with the key `visitor`. - The visitor signs a single PDF document. - The document will have one signature place, identified with the key `signer_signs_here`, that will be signed by the recipient `visitor` and will be added during the envelope creation using fixed positions. All other envelope settings use the default configuration: - The recipient will receive an email with a link to sign. - The account's default language, timezone, and timestamp format used. ## Prepare your Document The first step in the process is creating a PDF or DOCX file to upload. For this example, we prepared a document, where we put a line in the second page where we would like to place the signature. ### Example document Link: https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/privacy-fixed.pdf Download the PDF used in this example. Image: (/docs/api/guides/how-to/images/use-fixed-positions-1.png) ## Locate the Coordinates Fixed positions can be defined by specifying the page number, along with distances from the top of the page (`top`) and from the left side of the page (`left`), measured in points (1/72 of an inch). One of the main problems when using Fixed Positions is finding the exact coordinates. You can use any tool that indicates the position in points like image editors, or build your own. For this task, SignatureAPI provides a simple tool (https://cucho.github.io/place-positioner/) that helps, just open the file and click on the point you want. Image: (/docs/api/guides/how-to/images/use-fixed-positions-2.png) The `key` of the place will be `signer_signs_here`, and the position will be available at the sidebar. Image: (/docs/api/guides/how-to/images/use-fixed-positions-3.png) ## Create the Envelope When creating the envelope, add the array of fixed positions inside the document, and add the signature place object to the `places` array inside the document object, with the following properties: - `key`: Identifies the place within the document. Must match what you decided to use, in this case: `signer_signs_here`. - `type`: As this is a signature place, use the value `signature`. - `recipient_key`: The key of the recipient who will sign. Here, it's `visitor`. ```json // POST https://api.signatureapi.com/v1/envelopes // X-Api-Key: { "title": "Dummy Consent", "message": "Please review and sign the Dummy Privacy Policy for internal testing purposes. This document is not legally binding and is used solely for demonstration\n\nThank you for your cooperation.", "documents": [ { "url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/privacy-fixed.pdf", "fixed_positions": [ { "place_key": "signer_signs_here", "page": 2, "top": 471, "left": 73 } ], "places": [ { "key": "signer_signs_here", "type": "signature", "recipient_key": "visitor" } ] } ], "recipients": [ { "type": "signer", "key": "visitor", "name": "John Doe", "email": "john@example.com" } ] } ``` ## Result If successful, SignatureAPI will send John Doe (the recipient) an email with a link to sign. John can click the link and place his signature on the signature line. Image: (/docs/api/guides/how-to/images/use-fixed-positions-4.png) ## Try It Try this example in Postman (/docs/api/postman) using your test API key (/docs/api/test-mode) to create a free, non-binding test envelope. Test envelopes won't send emails, but you can review them in your dashboard. ## Keep Learning - Learn how to position a signature using placeholders (/docs/api/guides/how-to/use-placeholders) within the document. - Explore other types of places (/docs/api/resources/places/object), such as initials (/docs/api/resources/places/initials), text inputs (/docs/api/resources/places/text-input), or completion dates (/docs/api/resources/places/date). ## Multiple Recipients Signing In Parallel URL: https://signatureapi.com/docs/api/guides/how-to/parallel-signing Description: Send envelopes to multiple recipients simultaneously so they can sign in any order When sending an envelope for signatures, you can control how it's sent to recipients using the `routing` property in the **Envelope (/docs/api/resources/envelopes/object#param-routing)**. There are two options: **Sequential** and **Parallel**. By default, SignatureAPI uses sequential routing. With **Parallel Routing**, the envelope is sent simultaneously to all recipients. Each recipient can sign the document whenever they want, and there is no required signing order. In this example, we will create an envelope with: - A single PDF document. - Two recipients (signers) signing in parallel, with the keys `disclosing_party` and `receiving_party`. - Two signature places positioned with placeholders `[[disclosing_party_signature]]` and `[[receiving_party_signature]]`. All other envelope settings use the default configuration: - The recipient will receive an email with a link to sign. - The account's default language, timezone, and timestamp format used. ## Prepare your Document Placeholders are text markers within your PDF document indicating specific locations for items such as signatures, initials, or text inputs. Each placeholder follows the format `[[place_key]]`, where `place_key` uniquely identifies the specific location within your document. In this example, we have prepared a document containing the placeholders `[[disclosing_party_signature]]` and `[[receiving_party_signature]]`. These placeholders mark the exact positions within the document where the signatures corresponding to each key (`disclosing_party_signature` and `receiving_party_signature`) will be inserted. ### Example document Link: https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/dummy-nda.pdf Download the PDF used in this example. Image: (/docs/api/guides/how-to/images/parallel-signing-1.png) In our document, the placeholder is highlighted in blue for visibility. However, we recommend setting it to white so it remains invisible to the signer. ## Create the Envelope When creating the envelope: - Set `routing` to `parallel`. - Add your recipient objects to the recipients property of the Envelope in any order, as they'll be sent simultaneously. - Add the signature place objects to the `places` array inside the document object: - `key`: Must match the placeholder within the document file (e.g., `disclosing_party_signature`). - `type`: Set as `signature`. - `recipient_key`: Matches recipient keys (`disclosing_party` and `receiving_party`). ```json // POST https://api.signatureapi.com/v1/envelopes // X-Api-Key: { "title": "Dummy NDA", "message": "Please review and sign the following Non-Disclosure Agreement (NDA) for internal testing purposes. This document is not legally binding and is used solely for demonstration\n\nThank you for your cooperation.", "routing": "parallel", "documents": [ { "url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/dummy-nda.pdf", "places": [ { "key": "disclosing_party_signature", "type": "signature", "recipient_key": "disclosing_party" }, { "key": "receiving_party_signature", "type": "signature", "recipient_key": "receiving_party" } ] } ], "recipients": [ { "type": "signer", "key": "disclosing_party", "name": "Jane Doe", "email": "jane@example.com" }, { "type": "signer", "key": "receiving_party", "name": "Richard Roe", "email": "richard@example.com" } ] } ``` ## Result If successful, SignatureAPI will send emails to both Jane Doe ("disclosing\_party") and Richard Roe ("receiving\_party") with links to sign the document. Each signer places their signature on their designated signature line. Image: (/docs/api/guides/how-to/images/parallel-signing-2.png) Image: (/docs/api/guides/how-to/images/parallel-signing-3.png) ## Try It Try this example in Postman (/docs/api/postman) using your test API key (/docs/api/test-mode) to create a free, non-binding test envelope. Test envelopes won't send emails, but you can review them in your dashboard. ## Keep Learning - Learn about sequential signing (/docs/api/guides/how-to/sequential-signing) for workflows where the order of signing is important. - Explore other types of places (/docs/api/resources/places/object), such as initials (/docs/api/resources/places/initials), text inputs (/docs/api/resources/places/text-input), or completion dates (/docs/api/resources/places/date). - Position signatures using precise coordinates (/docs/api/guides/how-to/use-fixed-positions). ## Multiple Recipients Signing Sequentially URL: https://signatureapi.com/docs/api/guides/how-to/sequential-signing Description: Route envelopes to recipients one at a time in a specific signing order When sending an envelope for signatures, you can control how it’s sent to recipients using the `routing` property in the **Envelope (/docs/api/resources/envelopes/object#param-routing)**. There are two options: **Sequential** and **Parallel**. By default, SignatureAPI uses sequential routing. With **Sequential Routing**, the envelope is sent to one recipient at a time, in the order you specify in the envelope’s recipient array. The next recipient only receives the document after the previous one has signed. - A single PDF document. - Two recipients (signers) signing in sequential order, the first one with the key `disclosing_party` and the second one with the key `receiving_party`. - Two signature places positioned with placeholders `[[disclosing_party_signature]]` and `[[receiving_party_signature]]`. All other envelope settings use the default configuration: - The recipient will receive an email with a link to sign. - The account's default language, timezone, and timestamp format used. ## Prepare your Document Placeholders are text markers within your PDF document indicating specific locations for items such as signatures, initials, or text inputs. Each placeholder follows the format `[[place_key]]`, where `place_key` uniquely identifies the specific location within your document. In this example, we have prepared a document containing the placeholders `[[disclosing_party_signature]]` and `[[receiving_party_signature]]`. These placeholders mark the exact positions within the document where the signatures corresponding to each key (`disclosing_party_signature` and `receiving_party_signature`) will be inserted. ### Example document Link: https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/dummy-nda.pdf Download the PDF used in this example. Image: (/docs/api/guides/how-to/images/parallel-signing-1.png) In our document, the placeholder is highlighted in blue for visibility. However, we recommend setting it to white so it remains invisible to the signer. ## Create the Envelope When creating the envelope: - Set the property `routing` to `sequential` (optional, this is the default). - Add your recipient objects to the recipients property of the Envelope in the order you want. In this example we want the `disclosing_party` to be first, and the `receiving_party` the second, so we must add them in that order in the array. - Add the signature place object for the two places to the `places` array inside the document object, with the following properties: - `key`: This identifies the place within the document. Must match what’s inside the square brackets in the placeholder inside the document file, in this case: `disclosing_party_signature` for the `disclosing_party`, and `receiving_party_signature` for the `receiving_party`. - `type`: As this is a signature place, we use the value `signature`. - `recipient_key`: The key of the recipient that will sign in this place. In this example, `disclosing_party` and `receiving_party` ```json // POST https://api.signatureapi.com/v1/envelopes // X-Api-Key: { "title": "Dummy NDA", "message": "Please review and sign the following Non-Disclosure Agreement (NDA) for internal testing purposes. This document is not legally binding and is used solely for demonstration\n\nThank you for your cooperation.", "routing": "sequential", "documents": [ { "url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/dummy-nda.pdf", "places": [ { "key": "disclosing_party_signature", "type": "signature", "recipient_key": "disclosing_party" }, { "key": "receiving_party_signature", "type": "signature", "recipient_key": "receiving_party" } ] } ], "recipients": [ { "type": "signer", "key": "disclosing_party", "name": "Jane Doe", "email": "jane@example.com" }, { "type": "signer", "key": "receiving_party", "name": "Richard Roe", "email": "richard@example.com" } ] } ``` ## Result If the request is successful, SignatureAPI will send Jane Doe (the "disclosing\_party") an email with a link to sign, while Richard Roe (the "receiving\_party") will remain in `awaiting` status until Jane completes. Jane will click the link and place her signature on the signature line. Image: (/docs/api/guides/how-to/images/parallel-signing-2.png) After Jane completes, SignatureAPI will send Richard Roe (the "receiving\_party") an email with a link to sign. Richard will click the link, and will be able to place his signature on his signature line. Image: (/docs/api/guides/how-to/images/parallel-signing-3.png) ## Try It Try this example in Postman (/docs/api/postman) using your test API key (/docs/api/test-mode) to create a free, non-binding test envelope. Test envelopes won't send emails, but you can review them in your dashboard. ## Keep Learning - Learn about parallel signing (/docs/api/guides/how-to/parallel-signing) for workflows where the order of signing is not important. - Explore other types of places (/docs/api/resources/places/object), such as initials (/docs/api/resources/places/initials), text inputs (/docs/api/resources/places/text-input), or completion dates (/docs/api/resources/places/date). - Position signatures using precise coordinates (/docs/api/guides/how-to/use-fixed-positions). ## Send an Envelope to an Approver URL: https://signatureapi.com/docs/api/guides/how-to/send-to-approver Description: Route an envelope through an approver before it reaches a signer An **approver** is a recipient who reviews and authorizes a document without adding a signature. Use an approver when someone needs to authorize a document before it goes out for a formal signature. Common examples include a manager reviewing a contract before it reaches a client, or a compliance officer checking a document before finalization. In this example, we will create an envelope with: - A single PDF document. - Two recipients: an approver with the key `manager`, followed by a signer with the key `client`. - Sequential routing so the approver acts first. - One signature place assigned to the signer. The approver does not need a signature or initials place. All other envelope settings use the default configuration: - The signer will receive an email with a link to sign after the approver completes their step. - The account's default language, timezone, and timestamp format used. The `delivery_type` for approvers defaults to `none`, meaning the completed deliverable will not be automatically emailed to the approver. Set `delivery_type` to `email` if you want SignatureAPI to deliver the completed deliverable by email. ## Create the Envelope When creating the envelope: - Set `routing` to `sequential` (this is the default, but it is good practice to be explicit). - Add the approver recipient before the signer in the `recipients` array. The order of the array controls the routing order. - Set `"type": "approver"` on the approver recipient. - Add a signature place to the `places` array inside the document object, assigned to the signer only: - `key`: Identifies the place. Must match the placeholder in the document file (e.g., `client_signature`). - `type`: Set to `signature`. - `recipient_key`: Set to the signer's key (`client`). ```json // POST https://api.signatureapi.com/v1/envelopes // X-API-Key: key_test_... // Content-Type: application/json { "title": "Service Agreement", "routing": "sequential", "documents": [ { "url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/dummy-nda.pdf", "places": [ { "key": "client_signature", "type": "signature", "recipient_key": "client" } ] } ], "recipients": [ { "type": "approver", "key": "manager", "name": "Sarah Chen", "email": "sarah@company.com" }, { "type": "signer", "key": "client", "name": "Michael Torres", "email": "michael@client.com" } ] } ``` ## Result If the request is successful, Sarah Chen (the `manager`) enters the approver ceremony first. She reviews the document and, when satisfied, clicks **Approve**. Image: Approve button (/docs/images/approve-button.png) A confirmation screen appears once the approval is complete. Image: Approved confirmation (/docs/images/approved-confirmation.png) After Sarah approves, SignatureAPI routes the envelope to Michael Torres (the `client`). Michael receives an email with a link to sign the document and places his signature on the designated signature line. ## Try It Try this example in Postman (/docs/api/postman) using your test API key (/docs/api/test-mode) to create a free, non-binding test envelope. Test envelopes won't send emails, but you can review them in your dashboard. ## Keep Learning - Learn about sequential signing (/docs/api/guides/how-to/sequential-signing) for workflows with multiple signers in a specific order. - Learn about parallel signing (/docs/api/guides/how-to/parallel-signing) for workflows where signing order does not matter. - Explore the Approver (/docs/api/resources/recipients/approver) recipient reference for details on delivery and place assignments. - Explore other types of places (/docs/api/resources/places/object), such as text inputs (/docs/api/resources/places/text-input) that can be assigned to approvers. ## Prepare a Document Before Sending to Sign URL: https://signatureapi.com/docs/api/guides/how-to/prepare-before-signing Description: Use a preparer to fill in document fields before the envelope reaches the signer A **preparer** is a recipient who fills in document fields before the envelope reaches a signer. This is useful when one person needs to populate document data on behalf of another. For example, a sales representative can enter pricing, dates, or contract terms before the customer receives the document to sign. Preparers can complete text inputs, checkboxes, and dropdowns, but cannot add signatures or initials. After filling in all required fields, the preparer clicks **Finish**, and the envelope proceeds to the next recipient. In this example, we will create an envelope with: - A single PDF document. - A preparer (a sales representative) who fills in a text input field with the contract value. - A signer (the customer) who receives the document after the preparer has finished and adds their signature. - Sequential routing so the preparer acts before the signer. ## Prepare your Document Placeholders are text markers within your PDF document indicating specific locations for items such as signatures, initials, or text inputs. Each placeholder follows the format `[[place_key]]`, where `place_key` uniquely identifies the specific location within your document. In this example, we have prepared a document containing two placeholders: - `[[contract_value]]` marks the position where the preparer will enter the contract value as a text input. - `[[customer_signature]]` marks the position where the signer will place their signature. In our document, the placeholders are highlighted in blue for visibility. However, we recommend setting them to white so they remain invisible to recipients. ## Create the Envelope When creating the envelope: - Set `routing` to `sequential` (this is the default, but it is good practice to set it explicitly). - Add recipients in the order they should act. The preparer must appear before the signer in the recipients array. - Add place objects to the `places` array inside the document object: - For the preparer's text input: set `type` to `text_input` and `recipient_key` to the preparer's key. - For the signer's signature: set `type` to `signature` and `recipient_key` to the signer's key. ```json // POST https://api.signatureapi.com/v1/envelopes // X-API-Key: key_test_... // Content-Type: application/json { "title": "Sales Agreement", "routing": "sequential", "documents": [ { "url": "https://example.com/sales-agreement.pdf", "places": [ { "key": "contract_value", "type": "text_input", "recipient_key": "sales_rep" }, { "key": "customer_signature", "type": "signature", "recipient_key": "customer" } ] } ], "recipients": [ { "key": "sales_rep", "type": "preparer", "name": "Alex Smith", "email": "alex@company.com" }, { "key": "customer", "type": "signer", "name": "Jordan Lee", "email": "jordan@customer.com" } ] } ``` The `delivery_type` for preparers defaults to `none`, meaning the completed deliverable will not be automatically emailed to the preparer. Set `delivery_type` to `email` if you want SignatureAPI to deliver the completed deliverable by email. ## Result The preparer (Alex Smith) accesses the document first and fills in the contract value field. After clicking **Finish**, the envelope proceeds to the signer. Image: (/docs/images/prepared-confirmation.png) The signer (Jordan Lee) then receives the document with the preparer's field already filled in and can review the completed details before adding their signature. ## Try It Try this example in Postman (/docs/api/postman) using your test API key (/docs/api/test-mode) to create a free, non-binding test envelope. Test envelopes won't send emails, but you can review them in your dashboard. ## Keep Learning - Learn more about the preparer recipient type (/docs/api/resources/recipients/preparer) and how it differs from other recipient types. - Explore other types of places (/docs/api/resources/places/object), such as checkboxes (/docs/api/resources/places/checkbox), dropdowns (/docs/api/resources/places/dropdown), or text inputs (/docs/api/resources/places/text-input). - Learn about sequential signing (/docs/api/guides/how-to/sequential-signing) for workflows where the order of signing matters. - Learn about parallel signing (/docs/api/guides/how-to/parallel-signing) for workflows where recipients can sign in any order. ## Use Custom Authentication URL: https://signatureapi.com/docs/api/guides/how-to/custom-authentication Description: Authenticate recipients yourself and redirect them to the signing ceremony from your application With custom authentication, your application handles identity verification before the recipient accesses the signing ceremony. SignatureAPI provides a ceremony URL that you deliver directly, so the recipient can start signing without any additional authentication step on the SignatureAPI side. This approach is useful when: - Recipients are already authenticated in your system. - You want to integrate signing into your existing application flow without interrupting the user experience. - You need a specific authentication method, such as biometrics, SSO, or multi-factor. In this example, we will: 1. Create an envelope with custom authentication on the recipient's `ceremony` object. 2. Set `delivery_type` to `"none"` so the completed deliverable is not automatically emailed to the recipient. 3. Get the ceremony URL from the response and redirect the authenticated user. ## Create the Envelope Set the recipient's `ceremony` object with `authentication` set to `custom`. Provide: - `provider`: The name of your application or company. This appears in the audit log as: "John Doe has been authenticated by [provider]". - `data`: Key-value pairs that link the signing event to your authentication records. These values are recorded in the envelope audit log. Set `delivery_type` to `"none"` so the completed deliverable is not automatically emailed to the recipient. Your application is responsible for distributing the deliverable. ```json // POST https://api.signatureapi.com/v1/envelopes // X-API-Key: key_test_... // Content-Type: application/json { "title": "Service Agreement", "documents": [ { "url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/dummy-nda.pdf", "places": [ { "key": "client_signature", "type": "signature", "recipient_key": "client" } ] } ], "recipients": [ { "type": "signer", "key": "client", "name": "John Doe", "email": "john.doe@example.com", "delivery_type": "none", "ceremony": { "authentication": [ { "type": "custom", "provider": "My App", "data": { "Session ID": "a4f9e8b2-7c1d-4b2d-9a4b-e0c5d6f7a1b3", "User ID": "usr_88620999344", "Authenticated At": "2025-12-31T23:59:59Z" } } ] } } ] } ``` Include enough data in the `data` object to verify how the recipient was authenticated. Useful values include session IDs, user IDs, authentication timestamps, and authentication methods. These values appear in the audit log and may be needed to confirm identity in legal proceedings. ## Get the Ceremony URL The response includes the ceremony URL in `recipients[].ceremony.url`. Because authentication is `custom` (not `email_link`), the URL is available directly in the response. ```json // HTTP/1.1 201 Created { "id": "abcdef12-3456-7890-1234-abcdef123456", "title": "Service Agreement", "recipients": [ { "id": "re_01jxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "signer", "key": "client", "name": "John Doe", "email": "john.doe@example.com", "delivery_type": "none", "ceremony": { "authentication": [ { "type": "custom", "provider": "My App", "data": { "Session ID": "a4f9e8b2-7c1d-4b2d-9a4b-e0c5d6f7a1b3", "User ID": "usr_88620999344", "Authenticated At": "2025-12-31T23:59:59Z" } } ], "embeddable_in": [], "redirect_url": null, "redirect_delay": 3, "url_variant": "standard", "url": "https://sign.signatureapi.com/en/start?token=eyJhbGciOiJFUzI1NiIsInR..." }, //... } ], //... } ``` ## Redirect to the Ceremony URL Use the `url` from the ceremony object to redirect the recipient from your application to the signing ceremony. Because your application already authenticated the recipient, they land directly in the signing experience without any additional login step. ``` https://sign.signatureapi.com/en/start?token=eyJhbGciOiJFUzI1NiIsInR... ``` Treat ceremony URLs as sensitive credentials. Do not expose them in logs, public forums, or client-side code where unauthorized users could access them. Deliver the URL only to the authenticated recipient. After the recipient completes signing, SignatureAPI records the authentication event in the envelope audit log, including the provider name and all key-value pairs from the `data` object. ## Try It Try this example in Postman (/docs/api/postman) using your test API key (/docs/api/test-mode) to create a free, non-binding test envelope. Test envelopes won't send emails, but you can review them in your dashboard. ## Keep Learning - Learn about custom authentication (/docs/api/resources/ceremonies/authentication/custom) in depth, including audit log details and what data to include. - Explore ceremony URLs (/docs/api/resources/ceremonies/ceremony-url) for options such as short URLs and URL expiration. - Embed the signing ceremony (/docs/embedded/introduction) in your application using an iframe. - Learn about other authentication methods (/docs/api/resources/ceremonies/authentication/overview), such as email code (/docs/api/resources/ceremonies/authentication/email-code) or multiple authentication steps (/docs/api/resources/ceremonies/authentication/multiple). ## Use Document Templates URL: https://signatureapi.com/docs/api/guides/how-to/document-templates Description: Generate personalized documents from DOCX templates and dynamic data Document templates let you create a single DOCX file with merge fields and conditionals, then generate a personalized document for each envelope you send. Instead of editing files manually before each send, you provide the data and SignatureAPI handles the merge. For this example, we will create an envelope with: - One DOCX template containing merge fields for party names and a date. - Two signature places positioned with `[[place_key]]` placeholders. - Two recipients (signers): a service provider and a client. ## Create a Template Create a DOCX file in Microsoft Word and embed merge fields using double curly braces: `{{key}}`. When SignatureAPI processes the envelope, it replaces each field with the matching value from the `data` property you provide. A simple template might look like this: This Exploration Agreement is entered into as of \{\{date\}\}, between \{\{serviceProvider.name\}\} of \{\{serviceProvider.organization\}\} (the "Service Provider") and \{\{client.name\}\} of \{\{client.organization\}\} (the "Client"). You can reference nested objects using dot notation: `{{serviceProvider.name}}` reads the `name` key inside the `serviceProvider` object. To mark where signatures should appear, add `[[place_key]]` placeholders directly in the document. These work the same way as in PDF documents. In this example, the template contains the placeholders `[[provider_signs_here]]` and `[[client_signs_here]]`. Templates must be DOCX format. PDF files are not supported for template merging. If you get a cannot-parse-document (/docs/v1/errors/cannot-parse-document) error, open the file in Microsoft Word and save it again before uploading. ### Example template Link: https://pub-e5051420e98a4fdfb3fd42a62fbf06fa.r2.dev/dummy.docx Download the DOCX template used in this example. ## Create the Envelope When creating the envelope, set `format` to `docx` on the document object and provide merge values in the `data` property. Also include the `places` array with an entry for each `[[place_key]]` placeholder in the template. ```json // POST https://api.signatureapi.com/v1/envelopes // X-API-Key: key_test_... // Content-Type: application/json { "title": "Exploration Agreement", "message": "Please review the agreement and provide your signature.", "documents": [ { "url": "https://pub-e5051420e98a4fdfb3fd42a62fbf06fa.r2.dev/dummy.docx", "format": "docx", "data": { "date": "December 31st, 2025", "serviceProvider": { "name": "Jane Smith", "organization": "ACME Global, Inc." }, "client": { "name": "Michael J. Miller", "organization": "Miller Industries" } }, "places": [ { "key": "provider_signs_here", "type": "signature", "recipient_key": "service_provider" }, { "key": "client_signs_here", "type": "signature", "recipient_key": "client" } ] } ], "recipients": [ { "type": "signer", "key": "service_provider", "name": "Jane Smith", "email": "jane@example.com" }, { "type": "signer", "key": "client", "name": "Michael J. Miller", "email": "michael@example.com" } ] } ``` Key properties on the document object: - `format`: Must be `docx` when using a template. - `data`: An object whose keys match the merge fields in the template. Nested objects are supported. - `places`: An array of place objects. The `key` on each place must match the `[[place_key]]` placeholder in the template. ## Result SignatureAPI merges the template with the provided data and produces a final document. The merge fields are replaced with their values, and the signature places are rendered at the positions marked by the placeholders. Each recipient receives an email with a link to sign their respective place in the document. ## Conditionals Use conditionals to show or hide sections of the document based on your data. This is useful for clauses that apply only in certain situations, such as a mediation clause that is included only when both parties agree. ### If Use `{{if condition}}` and `{{endif}}` to include a block only when the condition is true. **Template:** Please read before proceeding. \{\{if showAlert\}\} Important: This document is for demonstration purposes only and is not legally binding. \{\{endif\}\} By signing, you acknowledge the terms above. **Data:** ```json { "showAlert": true } ``` With `"showAlert": true`, the alert paragraph appears. With `"showAlert": false`, it is omitted entirely. ### If-Else Use `{{if condition}}`, `{{else}}`, and `{{endif}}` to display one of two blocks depending on the value of a condition. **Template:** \{\{if mediation\}\} Any dispute shall be resolved by mediation, with each party bearing its own costs. \{\{else\}\} Any dispute shall be settled by arbitration, and the arbitrator's decision is final. \{\{endif\}\} With `"mediation": true`: Any dispute shall be resolved by mediation, with each party bearing its own costs. With `"mediation": false`: Any dispute shall be settled by arbitration, and the arbitrator's decision is final. ## Repeating lists If your data has an array of items, you can repeat a section of the document once per item. The classic example is a table where each row is one item. Suppose your envelope carries a list of events: ```json { "title": "Schedule", "documents": [ { "url": "https://www.example.com/schedule-template.docx", "format": "docx", "data": { "events": [ { "name": "Opening Reception", "date": "Mar 12", "guests": "120" }, { "name": "Closing Dinner", "date": "Mar 14", "guests": "80" } ] } } ] // ... } ``` In Word, build a table with a header row and a single data row. In the data row, mark where the repetition starts and ends with `{{#data.events}}` and `{{/data.events}}`: | Event | Date | Guests | |-------|------|--------| | \{\{#data.events\}\} \{\{data.events.name\}\} | \{\{data.events.date\}\} | \{\{data.events.guests\}\} \{\{/data.events\}\} | The data row repeats once per item. The header stays single because it sits outside the tags. There's one more rule: wrap your **entire document body** in `{{#data}}` ... `{{/data}}`. This outer wrapper is what makes paths like `{{data.events.name}}` work. This same pattern works for repeating paragraphs, bullets, multiple lists in one document, and more. See repeating regions (/docs/api/resources/documents/templates#repeating-regions) for the full reference. ## Try It Try this example in Postman (/docs/api/postman) using your test API key (/docs/api/test-mode) to create a free, non-binding test envelope. Test envelopes won't send emails, but you can review them in your dashboard. ## Keep Learning - Learn more about document template syntax (/docs/api/resources/documents/templates), including all supported field and conditional options. - Explore how to position signatures using placeholders (/docs/api/guides/how-to/use-placeholders) or fixed coordinates (/docs/api/guides/how-to/use-fixed-positions). - Learn about other types of places (/docs/api/resources/places/object), such as initials (/docs/api/resources/places/initials), text inputs (/docs/api/resources/places/text-input), or completion dates (/docs/api/resources/places/date). ## Embed Signing in a Web App URL: https://signatureapi.com/docs/api/guides/how-to/embed-web Description: Embed the signing ceremony directly in your web app using an iframe and JavaScript message events This guide shows how to embed the signing ceremony directly in your web application so users can sign documents without leaving your app. The process requires two sides: a **server** that creates the envelope and ceremony using your API key, and a **client** that displays the ceremony inside an iframe. In this example, we will: - Create an envelope with custom authentication, `embeddable_in` set to your domain, and `delivery_type` set to `"none"` so the deliverable is not automatically emailed. - Get the ceremony URL from the response and pass it to your client. - Embed the ceremony URL in an iframe with the required query parameters. - Listen for JavaScript message events to detect when signing is complete. ## Create the Envelope Create an envelope on your server with two important settings on the recipient: - Set `delivery_type` to `"none"` so the completed deliverable is not automatically emailed to the recipient. Your app is responsible for distributing the deliverable. - Set `ceremony.embeddable_in` to the origin where your app is hosted so the signing interface is allowed to load inside your iframe. Use `custom` authentication so the recipient does not need to go through an email flow. Your app handles authentication before presenting the ceremony. ```json // POST https://api.signatureapi.com/v1/envelopes // X-API-Key: key_test_... // Content-Type: application/json { "title": "Service Agreement", "documents": [ { "url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/privacy-placeholder.pdf", "places": [ { "key": "client_signature", "type": "signature", "recipient_key": "client" } ] } ], "recipients": [ { "type": "signer", "key": "client", "name": "Jane Doe", "email": "jane@example.com", "delivery_type": "none", "ceremony": { "authentication": [ { "type": "custom", "provider": "My App", "data": { "user_id": "usr_12345" } } ], "embeddable_in": [ "https://app.example.com" ] } } ] } ``` The response includes the ceremony URL in `recipients[].ceremony.url`. Because authentication is `custom`, the URL is available directly in the response. Pass this URL to your client so it can embed the ceremony. ```json // HTTP/1.1 201 Created { "id": "abcdef12-3456-7890-1234-abcdef123456", "title": "Service Agreement", "recipients": [ { "id": "re_01jxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "signer", "key": "client", "name": "Jane Doe", "email": "jane@example.com", "delivery_type": "none", "ceremony": { "authentication": [ { "type": "custom", "provider": "My App", "data": { "user_id": "usr_12345" } } ], "embeddable_in": [ "https://app.example.com" ], "redirect_url": null, "redirect_delay": 3, "url_variant": "standard", "url": "https://sign.signatureapi.com/en/start?token=eyJhbGciOiJFUzI1NiIsInR..." }, //... } ], //... } ``` Never call the API directly from the client. Your API key would be exposed to anyone using your app, giving them access to all your data in SignatureAPI. Always make API calls from your server and pass the ceremony URL to the client. ## Embed the Ceremony On the client, take the ceremony URL returned by your server and append two query parameters before using it as the iframe `src`: - `embedded=true` - Configures the signing UI for embedding and sets the correct Content Security Policy headers. - `event_delivery=message` - Delivers ceremony events as JavaScript `MessageEvent`s to your page. ```html