{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://artifacts.apis.io/signatureapi-com/json-schema/signatureapi-com-envelope-envelope-input-schema.json", "title": "Envelope", "description": "An **envelope** is a container that holds **documents** to be sent to **recipients** for signature. It defines and manages the signing process for those documents.\n\n### Lifecycle\n\nAn envelope moves through five statuses:\n\n1. `processing` -- The envelope is being prepared. Documents are validated and recipients are notified.\n2. `in_progress` -- The envelope has been sent to recipients and is waiting for all participants to complete their part.\n3. `completed` -- All recipients have completed their part (for example, signed). A **deliverable** is generated and sent to the recipients.\n4. `failed` -- An internal error occurred during processing. This is rare and triggers an automatic alert.\n5. `canceled` -- The signing process was intentionally stopped before completion via the Cancel Envelope endpoint.\n\n### Relationships\n\nAn envelope:\n\n- Has one or more **recipients** (signers, preparers, or approvers).\n- Has one or more **documents** (PDF or DOCX format).\n- Has one or more **deliverables** generated upon completion.", "x-generated": "2026-10-31", "x-method": "derived", "x-generator": "derive-json-schema.py", "x-source": "openapi/signatureapi-com-openapi.yml#/components/schemas/Envelope.EnvelopeInput", "x-schema-role": "model", "x-schema-direction": "input", "type": "object", "additionalProperties": false, "properties": { "label": { "$ref": "#/$defs/Envelope.Label" }, "metadata": { "$ref": "#/$defs/Envelope.Metadata" }, "message": { "$ref": "#/$defs/Envelope.Message" }, "title": { "$ref": "#/$defs/Envelope.Title" }, "topics": { "$ref": "#/$defs/Envelope.Topics" }, "branding": { "$ref": "#/$defs/Envelope.BrandingInput" }, "timezone": { "$ref": "#/$defs/Envelope.Timezone" }, "timestamp_format": { "$ref": "#/$defs/Envelope.TimestampFormat" }, "language": { "$ref": "#/$defs/Envelope.Language" }, "routing": { "$ref": "#/$defs/Envelope.Routing" }, "deliverable": { "description": "Defines the default deliverable configuration for the envelope. The deliverable is the final signed document package generated when all recipients complete the envelope. It is sent to all recipients unless their `recipient.delivery_type` is set to `none`.\n\nTwo types are available:\n\n- `standard` -- Includes signed documents and an audit log.\n- `simple` -- Includes signed documents only, without an audit log.\n\nIf no deliverable is provided, a `standard` deliverable is automatically generated.", "allOf": [ { "$ref": "#/$defs/Deliverable.DeliverableInput" } ] }, "attestation": { "$ref": "#/$defs/Envelope.Attestation" }, "documents": { "$ref": "#/$defs/Envelope.DocumentsInput" }, "recipients": { "$ref": "#/$defs/Envelope.RecipientsInput" }, "sender": { "$ref": "#/$defs/Envelope.SenderInput" } }, "required": [ "title", "documents", "recipients" ], "$defs": { "Ceremony.AuthenticationInput": { "x-schema-role": "property", "x-schema-direction": "input", "title": "Ceremony Authentication", "description": "The authentication methods the recipient must complete before accessing the ceremony. This is an ordered array. The recipient completes each method in sequence.\n\nFour authentication types are available:\n\n- **email_link** -- SignatureAPI sends the recipient an email with a clickable link to the ceremony.\n- **email_code** -- SignatureAPI sends the recipient a 9-digit verification code by email.\n- **custom** -- Your application handles authentication and shares the ceremony URL directly.\n- **identity_verification** -- The recipient proves their identity with an identity verification provider.\n\nThe first method decides who delivers the ceremony URL. When the first method is `email_link`, SignatureAPI emails the link and the `url` property is `null`. When it is `email_code` or `custom`, the `url` property is returned and your application delivers it. Methods after the first are challenges the recipient completes inside the ceremony, and they never change who delivers the URL.\n\nYou can combine multiple types for added security. For example:\n\n- `[email_link, email_code]` -- SignatureAPI emails the invitation link, and the recipient must also enter an emailed verification code to open the ceremony. Both emails come from SignatureAPI, so your application sends none.\n- `[custom, email_code]` -- your application authenticates the recipient and delivers the URL, and the recipient must also enter an emailed verification code.\n\nSee the constraints below:\n\n- `email_link` can only be the first step.\n- `custom` can only be the first step.\n- `email_link` and `custom` cannot be combined together.\n- `email_code` can appear at most once.\n- `identity_verification` can never be the first step, and can appear at most once. It is enabled per account.\n", "type": "array", "minItems": 1, "maxItems": 5, "items": { "oneOf": [ { "$ref": "#/$defs/Ceremony.EmailLinkAuthenticationInput" }, { "$ref": "#/$defs/Ceremony.EmailCodeAuthenticationInput" }, { "$ref": "#/$defs/Ceremony.CustomAuthenticationInput" }, { "$ref": "#/$defs/Ceremony.IdentityVerificationAuthenticationInput" } ] } }, "Ceremony.AuthenticationType": { "x-schema-role": "property", "x-schema-direction": "any", "type": "string", "title": "Ceremony Authentication Type", "description": "The type of authentication for the ceremony.\n\n- `email_link` -- SignatureAPI sends the recipient an email with a direct link to the ceremony.\n- `email_code` -- SignatureAPI sends the recipient a 9-digit verification code by email. The recipient requests the code from the ceremony and enters it there.\n- `custom` -- Your application handles authentication and shares the ceremony URL directly.\n- `identity_verification` -- The recipient proves their identity with an identity verification provider. This is a challenge that follows a main type, so it cannot be the first item of the array.\n\nAuthentication is an ordered array, and the **first** method decides who delivers the ceremony URL:\n\n- `email_link` first -- SignatureAPI emails the link, and the `url` property is `null`. This still holds when other methods follow it, so `[email_link, email_code]` sends both the invitation email and the code by email, and your application sends nothing.\n- `email_code` or `custom` first -- the `url` property is returned in the response, and your application delivers it.\n", "enum": [ "email_link", "email_code", "custom", "identity_verification" ] }, "Ceremony.CeremonyInput": { "x-schema-role": "model", "x-schema-direction": "input", "title": "Ceremony", "description": "A **ceremony** is the interactive session where a **recipient** authenticates and performs their actions on an **envelope**. Depending on the recipient type, these actions include signing, approving, or preparing documents.\n\nEach recipient can have one active ceremony at a time. When you create a new ceremony for a recipient, any previous ceremonies are automatically revoked.\n\n### Lifecycle\n\nA ceremony moves through the following statuses:\n\n- **pending** -- The ceremony is created but the envelope is not yet active.\n- **active** -- The ceremony is ready for the recipient to access.\n- **completed** -- The recipient finished their actions.\n- **declined** -- The recipient declined to act.\n- **revoked** -- The ceremony was replaced by a new one or canceled.\n\n### Authentication\n\nEvery ceremony requires at least one authentication method. You can combine multiple methods that the recipient must complete in sequence before accessing the ceremony.\n", "type": "object", "additionalProperties": false, "properties": { "authentication": { "$ref": "#/$defs/Ceremony.AuthenticationInput" }, "embeddable_in": { "$ref": "#/$defs/Ceremony.EmbeddableIn" }, "redirect_url": { "$ref": "#/$defs/Ceremony.RedirectUrl" }, "redirect_delay": { "$ref": "#/$defs/Ceremony.RedirectDelay" }, "url_variant": { "$ref": "#/$defs/Ceremony.UrlVariant" } }, "required": [ "authentication" ] }, "Ceremony.CustomAuthenticationData": { "x-schema-role": "property", "x-schema-direction": "any", "type": "object", "title": "Custom Authentication Data", "description": "Key-value pairs that link the ceremony to your authentication records. This data appears in the envelope audit log.\n\nInclude information that can verify how the recipient was authenticated, such as session IDs, timestamps, or user identifiers. Avoid including unnecessary sensitive details.\n", "minProperties": 1, "maxProperties": 10, "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 1000 }, "propertyNames": { "type": "string", "minLength": 1, "maxLength": 100 }, "unevaluatedProperties": false }, "Ceremony.CustomAuthenticationInput": { "x-schema-role": "model", "x-schema-direction": "input", "title": "Custom Authentication", "description": "Custom authentication lets your application handle recipient verification. SignatureAPI provides a ceremony URL that you share with the recipient through your preferred channel.\n\nUse this method when recipients are already authenticated in your system, or when you need full control over the authentication flow. This is common for embedded signing experiences.\n\nYou must provide a `provider` name and a `data` object with key-value pairs that link the ceremony to your authentication records. Both appear in the envelope audit log.\n", "type": "object", "additionalProperties": false, "properties": { "type": { "allOf": [ { "$ref": "#/$defs/Ceremony.AuthenticationType" }, { "const": "custom" } ] }, "provider": { "$ref": "#/$defs/Ceremony.CustomAuthenticationProvider" }, "data": { "$ref": "#/$defs/Ceremony.CustomAuthenticationData" } }, "required": [ "type", "provider", "data" ] }, "Ceremony.CustomAuthenticationProvider": { "x-schema-role": "property", "x-schema-direction": "any", "type": "string", "minLength": 1, "maxLength": 100, "title": "Custom Authentication Provider", "description": "The name of your company or application that authenticated the recipient. This value appears in the envelope audit log as the authentication provider.\n" }, "Ceremony.EmailCodeAuthenticationInput": { "x-schema-role": "model", "x-schema-direction": "input", "title": "Email Code Authentication", "description": "Email code authentication sends the recipient a 9-digit verification code by email. The recipient requests the code from the ceremony and enters it to continue.\n\nUse this method to add an extra layer of verification to a ceremony. Where it sits in the `authentication` array decides who delivers the ceremony URL:\n\n- **First in the array** -- the `url` property is returned in the response and your application delivers it through the channel of your choice. SignatureAPI sends no invitation email, only the code email.\n- **After `email_link`** -- SignatureAPI emails the invitation link as usual and the `url` property is `null`. The code becomes a second step inside the ceremony, and SignatureAPI sends both emails.\n- **After `custom`** -- your application authenticates the recipient and delivers the returned URL, and the code is a second step.\n", "type": "object", "additionalProperties": false, "properties": { "type": { "allOf": [ { "$ref": "#/$defs/Ceremony.AuthenticationType" }, { "const": "email_code" } ] } }, "required": [ "type" ] }, "Ceremony.EmailLinkAuthenticationInput": { "x-schema-role": "model", "x-schema-direction": "input", "title": "Email Link Authentication", "description": "Email link authentication sends the recipient an email with a direct link to the ceremony. The recipient clicks the link to authenticate and access the signing session.\n\nThis is the default authentication method. If you create an envelope without specifying a ceremony, SignatureAPI uses email link authentication automatically.\n\nBecause SignatureAPI delivers the link itself, the ceremony's `url` property is `null`. This holds when other methods follow it in the array: `[email_link, email_code]` still has SignatureAPI send the invitation email, and adds an emailed verification code as a second step.\n\nYou can customize the email subject and message body per recipient using `subject_override` and `message_override`. If not set, the envelope title and message are used.\n", "type": "object", "additionalProperties": false, "properties": { "type": { "allOf": [ { "$ref": "#/$defs/Ceremony.AuthenticationType" }, { "const": "email_link" } ] }, "subject_override": { "$ref": "#/$defs/Ceremony.EmailLinkSubjectOverride" }, "message_override": { "$ref": "#/$defs/Ceremony.EmailLinkMessageOverride" } }, "required": [ "type" ] }, "Ceremony.EmailLinkMessageOverride": { "x-schema-role": "property", "x-schema-direction": "any", "type": [ "string", "null" ], "title": "Email Message Override", "description": "A custom message body for the ceremony invitation email sent to this recipient. Supports basic Markdown: `**bold**`, `*italic*`, and `\\n\\n` for paragraph breaks.\n\nIf not set, the envelope message is used. Set to an empty string `\"\"` to send the email with no message body.\n", "maxLength": 2000 }, "Ceremony.EmailLinkSubjectOverride": { "x-schema-role": "property", "x-schema-direction": "any", "type": [ "string", "null" ], "title": "Email Subject Override", "description": "A custom subject line for the ceremony invitation email sent to this recipient.\n\nIf not set, the envelope title is used as the subject line.\n", "minLength": 1, "maxLength": 500 }, "Ceremony.EmbeddableIn": { "x-schema-role": "property", "x-schema-direction": "any", "type": "array", "title": "Embeddable In", "description": "Origins allowed to embed the ceremony in an iframe.\n\nThese values set the `frame-ancestors` directive in the ceremony's Content Security Policy (CSP) header.\n\nEach source is typically a scheme and host, like `https://app.example.com`. Wildcards are supported, like `https://*.example.com`. Only the origin (scheme and host) is used; the path is ignored.\n\nIf empty, the ceremony cannot be embedded in an iframe.\n\nSet to `['*']` to allow embedding from any origin. This is recommended only for development.\n", "maxItems": 10, "items": { "type": "string", "minLength": 1, "maxLength": 100 }, "default": [] }, "Ceremony.IdentityVerificationAuthenticationInput": { "x-schema-role": "model", "x-schema-direction": "input", "title": "Identity Verification Authentication", "description": "Identity verification sends the recipient to an identity verification provider before they can access the ceremony. The recipient proves who they are with the `method` you choose, and returns to the ceremony once the provider reports a result.\n\nUse this method when a signature needs a verified identity behind it, for example for qualified or advanced electronic signatures.\n\nIdentity verification is a challenge, not a main authentication type. It always follows a main type such as `email_link` or `custom`, so it cannot be the first item of the `authentication` array, and it can appear at most once.\n\nYou must provide a `method`. The `provider` is optional and defaults to `stub`.\n\nIdentity verification is enabled per account. Contact support to turn it on before using it.\n", "type": "object", "additionalProperties": false, "properties": { "type": { "allOf": [ { "$ref": "#/$defs/Ceremony.AuthenticationType" }, { "const": "identity_verification" } ] }, "method": { "$ref": "#/$defs/Ceremony.IdentityVerificationMethod" }, "provider": { "$ref": "#/$defs/Ceremony.IdentityVerificationProvider" } }, "required": [ "type", "method" ] }, "Ceremony.IdentityVerificationMethod": { "x-schema-role": "property", "x-schema-direction": "any", "type": "string", "title": "Identity Verification Method", "description": "The identity verification the recipient must complete. Required — there is no automatic selection.\n\n- `document_selfie` -- The recipient photographs a government-issued identity document and takes a selfie for a liveness and face match.\n- `eid` -- The recipient authenticates with a national or government-issued electronic identity scheme.\n- `video_ident` -- The recipient completes a video session with an agent who checks their identity document.\n- `reuse_credential` -- The recipient reuses an identity credential they already hold with the provider, without verifying again.\n", "x-enum-descriptions": { "document_selfie": "Identity document photo plus a selfie liveness and face match.", "eid": "National or government-issued electronic identity scheme.", "video_ident": "Live video session with an agent.", "reuse_credential": "Reuse of an identity credential the recipient already holds with the provider." }, "enum": [ "document_selfie", "eid", "video_ident", "reuse_credential" ] }, "Ceremony.IdentityVerificationProvider": { "x-schema-role": "property", "x-schema-direction": "any", "type": "string", "title": "Identity Verification Provider", "description": "The identity verification provider that performs the check. Optional — defaults to `stub`.\n\n- `stub` -- A built-in test provider that simulates the verification without contacting a real identity service.\n", "x-enum-descriptions": { "stub": "Built-in test provider that simulates the verification." }, "default": "stub", "enum": [ "stub" ] }, "Ceremony.RedirectDelay": { "x-schema-role": "property", "x-schema-direction": "any", "type": [ "integer", "null" ], "title": "Redirect Delay", "minimum": 0, "maximum": 20, "description": "The delay in seconds before the ceremony redirects to `redirect_url` (standalone) or emits completion events (embedded).\n\nSet to `0` for an immediate redirect. Defaults to `3` seconds. Maximum is `20` seconds.\n", "default": 3 }, "Ceremony.RedirectUrl": { "x-schema-role": "property", "x-schema-direction": "any", "type": [ "string", "null" ], "title": "Redirect URL", "format": "uri", "pattern": "^https://.*$", "description": "The URL the recipient is redirected to after the ceremony ends. Must use HTTPS. Embedded ceremonies ignore this redirect.\n\nSignatureAPI appends these query parameters to the URL:\n- `ceremony_result` -- The outcome: `ceremony.completed`, `ceremony.declined`, or `ceremony.failed`.\n- `envelope_id` -- The ID of the envelope.\n- `recipient_id` -- The ID of the recipient.\n\nFor example: `https://example.com/?ceremony_result=ceremony.completed&envelope_id=...&recipient_id=...`\n\nIf not set, the ceremony does not redirect.\n", "default": null }, "Ceremony.UrlVariant": { "x-schema-role": "property", "x-schema-direction": "any", "type": "string", "title": "URL Variant", "description": "The format of the ceremony URL.\n\n- `standard` -- Full-length URL. Works for most use cases.\n- `short` -- Shortened URL. Useful for space-constrained channels like SMS or push notifications.\n\nDefaults to `standard`.\n", "enum": [ "standard", "short" ], "default": "standard" }, "Deliverable.DeliverableInput": { "x-schema-role": "model", "x-schema-direction": "input", "title": "Deliverable", "description": "A **deliverable** is the final PDF output generated after an envelope is completed. It contains the signed documents and may include an audit trail, depending on the type.\n\nThe `type` field determines the deliverable variant:\n\n- `standard` -- Includes signed documents and an audit log with a certificate of completion.\n- `simple` -- Includes signed documents only, without an audit log.\n\n### Lifecycle\n\nA deliverable moves through these statuses:\n\n1. `pending` -- Waiting for the envelope to complete.\n2. `processing` -- The envelope is completed and the deliverable is being generated. This usually takes a few seconds.\n3. `generated` -- The deliverable is ready. The `url` field contains a download link.\n4. `failed` -- Generation failed. This is rare and triggers an automatic alert to support.\n\n### Default behavior\n\nWhen an envelope is created without an explicit deliverable configuration, a `standard` deliverable is generated automatically upon completion. You can also create additional deliverables after the envelope completes using the Create Deliverable endpoint.\n", "oneOf": [ { "$ref": "#/$defs/Deliverable.StandardInput" }, { "$ref": "#/$defs/Deliverable.SimpleInput" }, { "type": "null" } ] }, "Deliverable.IncludedDocuments": { "x-schema-role": "model", "x-schema-direction": "any", "title": "Included Documents", "type": "array", "description": "The keys of the documents to include in the deliverable.\n\nBy default, all documents in the envelope are included. Use this field to create a deliverable with only a subset of documents, for example to generate separate deliverables for different recipients.", "items": { "$ref": "#/$defs/Document.Key" }, "minItems": 1, "maxItems": 10 }, "Deliverable.Language": { "x-schema-role": "property", "x-schema-direction": "any", "allOf": [ { "title": "Language", "description": "The language used for system-generated text in the audit log, such as labels and the certificate of completion. This does not affect the signed document content.\n\nIf not specified, the language of the envelope is used.\n" }, { "$ref": "#/$defs/Envelope.Language" } ] }, "Deliverable.Name": { "x-schema-role": "property", "x-schema-direction": "any", "title": "Deliverable Name", "description": "A user-provided name for this deliverable. Use this to identify deliverables when an envelope has more than one.\n\nMust start with a lowercase letter and contain only lowercase letters, numbers, and underscores.", "type": [ "string", "null" ], "pattern": "^[a-z][a-z0-9_]*$", "minLength": 1, "maxLength": 32 }, "Deliverable.Password": { "x-schema-role": "property", "x-schema-direction": "input", "type": "string", "title": "Deliverable Password", "minLength": 4, "maxLength": 32, "pattern": "^[A-Za-z0-9]+$", "description": "A password used to encrypt the deliverable PDF with AES-128 encryption. Recipients must enter this password to open the file.\n\nThe password must be between 4 and 32 characters long and contain only uppercase letters (A-Z), lowercase letters (a-z), and numbers (0-9). Special characters are not supported due to PDF reader compatibility.\n\nFor strong protection, use at least 12 characters with a random mix of uppercase, lowercase, and numbers.\n\nIn API responses, the password is masked as `********`.\n\nTo use this feature, contact support to enable it on your account.\n" }, "Deliverable.SimpleInput": { "x-schema-role": "model", "x-schema-direction": "input", "title": "Simple Deliverable", "description": "A **simple deliverable** is a PDF that contains only the signed documents. No audit log pages are included in the output.\n\nThe audit trail 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.\n\nYou can customize which documents are included using the `included_documents` field. Password protection is also available.\n", "type": "object", "additionalProperties": false, "properties": { "name": { "$ref": "#/$defs/Deliverable.Name" }, "type": { "allOf": [ { "$ref": "#/$defs/Deliverable.Type" }, { "const": "simple" } ] }, "included_documents": { "$ref": "#/$defs/Deliverable.IncludedDocuments" }, "password": { "$ref": "#/$defs/Deliverable.Password" } }, "required": [ "type" ] }, "Deliverable.StandardInput": { "x-schema-role": "model", "x-schema-direction": "input", "title": "Standard Deliverable", "description": "A **standard deliverable** is a PDF that contains the signed documents and an audit log. The audit log records each action taken during the signing process and includes a certificate of completion.\n\nThe `language`, `timezone`, and `timestamp_format` fields control how system-generated text and timestamps appear in the audit log. These settings do not affect the signed document content.\n\nIf not specified, these values default to the envelope's settings.\n\nYou can customize which documents are included using the `included_documents` field. Password protection is also available.\n", "type": "object", "additionalProperties": false, "properties": { "name": { "$ref": "#/$defs/Deliverable.Name" }, "type": { "allOf": [ { "$ref": "#/$defs/Deliverable.Type" }, { "const": "standard" } ] }, "timezone": { "$ref": "#/$defs/Deliverable.Timezone" }, "timestamp_format": { "$ref": "#/$defs/Deliverable.TimestampFormat" }, "language": { "$ref": "#/$defs/Deliverable.Language" }, "included_documents": { "$ref": "#/$defs/Deliverable.IncludedDocuments" }, "password": { "$ref": "#/$defs/Deliverable.Password" } }, "required": [ "type" ] }, "Deliverable.TimestampFormat": { "x-schema-role": "property", "x-schema-direction": "any", "allOf": [ { "title": "Timestamp Format", "description": "The format used for timestamps in the audit log. This controls how dates and times appear in the system-generated pages of the deliverable.\n\nIf not specified, the timestamp format of the envelope is used.\n" }, { "$ref": "#/$defs/Envelope.TimestampFormat" } ] }, "Deliverable.Timezone": { "x-schema-role": "property", "x-schema-direction": "any", "allOf": [ { "title": "Deliverable Timezone", "description": "The timezone used for timestamps in the audit log. This does not affect the signed document content or the `created_at` and `generated_at` API fields.\n\nIf not specified, the timezone of the envelope is used.\n" }, { "$ref": "#/$defs/Envelope.Timezone" } ] }, "Deliverable.Type": { "x-schema-role": "property", "x-schema-direction": "any", "type": "string", "title": "Deliverable Type", "enum": [ "simple", "standard" ], "description": "The type of the deliverable.\n\n- `standard` -- Includes signed documents and an audit log with a certificate of completion.\n- `simple` -- Includes signed documents only, without an audit log.\n" }, "Document.Data": { "x-schema-role": "property", "x-schema-direction": "any", "type": "object", "title": "Document Data", "description": "Template data used to fill dynamic fields in a DOCX template. Each key corresponds to a `{{key}}` placeholder in the template file.\n\nKeys must be alphanumeric and at most 32 characters. Values can be strings, booleans, or nested objects. Nested keys map to dot-notation placeholders (e.g., a key `person` with nested key `name` fills `{{person.name}}`).", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 32, "pattern": "^[a-zA-Z0-9]+$", "description": "Keys must be up to 32 alphanumeric characters." }, "unevaluatedProperties": false, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "boolean" }, { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "boolean" } ] } } ] }, "default": {} }, "Document.DocumentInput": { "x-schema-role": "model", "x-schema-direction": "input", "title": "Document", "description": "A **document** is a file within an envelope that recipients interact with. Each document is either a PDF or a DOCX file.\n\nThe `format` field determines the document type:\n\n- **`pdf`** -- A PDF file. Supports places positioned by placeholders or fixed coordinates.\n- **`docx`** -- A DOCX file. Supports template fields for dynamic content in addition to places.\n\n### Document source\n\nProvide a publicly accessible URL when creating a document. You can host files yourself or use the **Upload** endpoint to upload files to SignatureAPI first.\n\n### Places\n\nEach document can have **places** -- interactive fields like signatures, text inputs, and checkboxes that recipients fill in. Places can also display information such as dates and static text.\n\nPlaces are positioned in two ways:\n\n- **Placeholders** embedded in the document text (e.g., `[[place_key]]`).\n- **Fixed positions** specified by page number and coordinates in points.\n\n### Relationships\n\nA document:\n\n- Belongs to one **envelope**.\n- Has zero or more **places**.\n", "oneOf": [ { "$ref": "#/$defs/Document.DocxDocumentInput" }, { "$ref": "#/$defs/Document.PdfDocumentInput" } ] }, "Document.DocxDocumentInput": { "x-schema-role": "model", "x-schema-direction": "input", "title": "Docx Document", "description": "A DOCX document within an envelope.\n\nDOCX documents support **templates** -- dynamic content generation from a static template combined with data you provide. Use double curly braces in your DOCX file to mark template fields (e.g., `{{name}}`). Nested objects are supported (e.g., `{{person.address.city}}`). Conditionals (if and if-else) control which sections appear in the final document.\n\nProvide template data in the `data` field when creating the envelope. SignatureAPI merges the template with your data to produce the final document.\n\nDOCX documents also support places and fixed positions, just like PDF documents.\n", "type": "object", "additionalProperties": false, "properties": { "key": { "$ref": "#/$defs/Document.Key" }, "title": { "$ref": "#/$defs/Document.Title" }, "url": { "$ref": "#/$defs/Document.Url" }, "format": { "allOf": [ { "$ref": "#/$defs/Document.Format" }, { "const": "docx" } ] }, "data": { "$ref": "#/$defs/Document.Data" }, "fixed_positions": { "$ref": "#/$defs/Document.FixedPositions" }, "places": { "$ref": "#/$defs/Document.PlacesInput" } }, "required": [ "url", "format" ] }, "Document.FixedPosition": { "x-schema-role": "model", "x-schema-direction": "any", "title": "Fixed Position", "description": "A coordinate-based position that places a field at an exact location on a document page. Use fixed positions as an alternative to embedding placeholders in the document text.\n\nCoordinates are measured in **points** (1/72 of an inch) from the top-left corner of the page. The coordinates reference the bottom-left corner of the place.", "type": "object", "properties": { "page": { "$ref": "#/$defs/Document.FixedPositionPage" }, "top": { "$ref": "#/$defs/Document.FixedPositionTop" }, "left": { "$ref": "#/$defs/Document.FixedPositionLeft" }, "place_key": { "description": "The key of the place to position. For a `radio_group`, position each option individually with a `group_key:option_value` key (for example `billing_cycle:monthly`).", "anyOf": [ { "$ref": "#/$defs/Place.Key" }, { "$ref": "#/$defs/Place.RadioGroupMemberKey" } ] } }, "required": [ "page", "top", "left", "place_key" ] }, "Document.FixedPositionLeft": { "x-schema-role": "property", "x-schema-direction": "any", "title": "Left Distance", "description": "The horizontal distance from the left edge of the page to the bottom-left corner of the place. Measured in points (1/72 of an inch). Decimal values are allowed.\n\nFor example, `72` is 1 inch from the left edge.", "type": "number" }, "Document.FixedPositionPage": { "x-schema-role": "property", "x-schema-direction": "any", "title": "Page Number", "description": "The page number where the place is positioned. Page numbering starts at 1.", "type": "integer" }, "Document.FixedPositionTop": { "x-schema-role": "property", "x-schema-direction": "any", "title": "Top Distance", "description": "The vertical distance from the top edge of the page to the bottom-left corner of the place. Measured in points (1/72 of an inch). Decimal values are allowed.\n\nFor example, `360` is 5 inches from the top edge.", "type": "number" }, "Document.FixedPositions": { "x-schema-role": "property", "x-schema-direction": "any", "title": "Fixed Positions", "description": "A list of coordinate-based positions that place fields at exact locations on document pages. Each entry maps a `place_key` to a specific page and coordinate.\n\nUse fixed positions as an alternative to embedding `[[place_key]]` placeholders in the document text.", "type": "array", "items": { "$ref": "#/$defs/Document.FixedPosition" }, "default": [] }, "Document.Format": { "x-schema-role": "property", "x-schema-direction": "any", "type": "string", "title": "Document Format", "description": "The file format of the document. Determines which features are available.\n\n- `pdf` -- Standard PDF file. Supports places via placeholders or fixed positions.\n- `docx` -- Microsoft Word file. Supports template fields for dynamic content in addition to places.", "enum": [ "pdf", "docx" ] }, "Document.Key": { "x-schema-role": "property", "x-schema-direction": "any", "title": "Document Key", "description": "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.\n\nOnly lowercase letters, numbers, and underscores are allowed. Must start with a letter.\n\nIf not provided, a key is generated automatically.", "type": "string", "pattern": "^[a-z][a-z0-9_]*$", "minLength": 1, "maxLength": 32 }, "Document.PdfDocumentInput": { "x-schema-role": "model", "x-schema-direction": "input", "title": "Pdf Document", "description": "A PDF document within an envelope.\n\nPDF documents support places positioned by either placeholders embedded in the PDF text or fixed positions specified by coordinates. Use placeholders for convenience or fixed positions for precise control.\n", "type": "object", "additionalProperties": false, "properties": { "key": { "$ref": "#/$defs/Document.Key" }, "title": { "$ref": "#/$defs/Document.Title" }, "url": { "$ref": "#/$defs/Document.Url" }, "format": { "allOf": [ { "$ref": "#/$defs/Document.Format" }, { "const": "pdf" } ] }, "fixed_positions": { "$ref": "#/$defs/Document.FixedPositions" }, "places": { "$ref": "#/$defs/Document.PlacesInput" } }, "required": [ "url", "format" ] }, "Document.PlacesInput": { "x-schema-role": "property", "x-schema-direction": "input", "title": "Places", "description": "The places attached to this document. Places are interactive fields or informational elements positioned on the document pages.\n\nEach place has a `type` that determines its behavior. Input types include signatures, initials, text inputs, checkboxes, and dropdowns. Informational types include static text, dates, and recipient details.\n\nPlaces are positioned using either **placeholders** embedded in the document text or **fixed positions** specified in the `fixed_positions` array.\n", "type": "array", "items": { "$ref": "#/$defs/Place.PlaceInput" }, "default": [] }, "Document.Title": { "x-schema-role": "property", "x-schema-direction": "any", "type": [ "string", "null" ], "title": "Document Title", "description": "An optional display name for the document. When set, the title is shown to recipients during the signing ceremony and in deliverables.\n\nIf not provided, defaults to `null`.", "minLength": 1, "maxLength": 500, "default": null }, "Document.Url": { "x-schema-role": "property", "x-schema-direction": "any", "type": "string", "format": "uri", "title": "Document Url", "description": "The URL where the document or template file is located. Must be publicly accessible.\n\nSupported hosting services include Amazon S3, AWS CloudFront, Google Cloud Storage, Azure Blob Storage, Cloudflare R2, Dropbox, and Google Drive.\n\nAlternatively, use the **Create Upload** endpoint to upload a file to SignatureAPI first, then use the returned `url` value here.", "maxLength": 2048 }, "Envelope.Attestation": { "x-schema-role": "property", "x-schema-direction": "any", "title": "Deliverable Attestation", "description": "Specifies the regulatory or compliance attestation applied to a completed envelope. Attestations are optional and enable adherence to country-specific e-signature regulations.\n\n- `none` -- No attestation. This is the default.\n- `mx_nom151` -- Complies with Mexico's NOM-151 standard for data message preservation and document digitization. A preservation certificate (_Constancia de Conservacion_) in ASN.1 format is attached to the deliverable. A verification link is included on the last page of the document. This option must be enabled at the account level before use. An additional fee of $0.10 per completed envelope applies.\n- `br_icp_brasil` -- Complies with Brazil's ICP-Brasil trusted timestamping (_carimbo do tempo_) under MP 2.200-2/2001. An RFC 3161 timestamp issued by an ICP-Brasil accredited authority is embedded in the deliverable as a PDF document timestamp, verifiable in standard PDF readers. This option must be enabled at the account level before use.\n", "type": "string", "enum": [ "none", "mx_nom151", "br_icp_brasil" ], "default": "none" }, "Envelope.BrandingAccentColor": { "x-schema-role": "property", "x-schema-direction": "any", "title": "Branding Accent Color", "type": "string", "description": "The accent color applied to buttons in emails and the signing ceremony. Specified as a hex color code (e.g., `#2463eb`).\n\nThe 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.\n\nDoes not affect input fields, checkboxes, or signature boxes. Defaults to `#2463eb` (blue) if not specified.\n", "pattern": "^#[a-fA-F0-9]{6}$", "default": "#2463eb" }, "Envelope.BrandingEmailFooter": { "x-schema-role": "property", "x-schema-direction": "any", "type": [ "string", "null" ], "title": "Email Footer", "description": "A custom footer included at the bottom of all emails sent to recipients for this envelope. The footer appears after SignatureAPI's standard footer content.\n\nUse this for company disclaimers, privacy notices, or contact information.\n\nThe footer supports a subset of Markdown formatting:\n- `**bold**` for bold text\n- `*italic*` for italic text\n- `\\n\\n` for paragraph breaks", "minLength": 1, "maxLength": 10000, "default": null }, "Envelope.BrandingEmailFrom": { "x-schema-role": "property", "x-schema-direction": "any", "x-docs-hidden": true, "type": "string", "format": "email", "title": "Email From", "description": "The email address shown in the \"From\" field of emails sent to recipients.\n\nDefaults to `noreply@signatureapi.com`. To use a custom email address from your own domain, contact support at support@signatureapi.com. DNS record configuration is required for custom domain email delivery.", "maxLength": 320, "default": "noreply@signatureapi.com" }, "Envelope.BrandingEmailLogoPosition": { "x-schema-role": "property", "x-schema-direction": "any", "type": "string", "title": "Logo Position", "enum": [ "left", "center", "right" ], "default": "left", "description": "The horizontal alignment of the logo in recipient emails.\n\n- `left` -- Aligns the logo to the left.\n- `center` -- Centers the logo.\n- `right` -- Aligns the logo to the right.\n\nDefaults to `left` if not specified.\n" }, "Envelope.BrandingInput": { "x-schema-role": "property", "x-schema-direction": "input", "type": "object", "additionalProperties": false, "title": "Envelope Branding", "description": "Customizes the visual appearance of the signing ceremony and recipient emails. Branding does not affect internal notifications or the signed documents themselves.\n\nThe following branding options are available:\n\n- **logo** -- A logo image displayed in the header of emails and the signing ceremony. Must be a PNG file uploaded to the Library.\n- **accent_color** -- A hex color code applied to buttons in emails and the signing ceremony. Must meet a 4.5:1 contrast ratio against white (WCAG). Defaults to `#2463eb`.\n- **email.footer** -- A custom footer appended to emails. Supports Markdown for bold, italic, and paragraph breaks. Useful for disclaimers or contact information.\n- **email.logo_position** -- Controls logo alignment in emails: `left`, `center`, or `right`. Defaults to `left`.\n- **email.from** -- The email address shown in the \"From\" field. Defaults to `noreply@signatureapi.com`. Custom domains require DNS configuration.", "properties": { "logo": { "$ref": "#/$defs/Envelope.BrandingLogo" }, "accent_color": { "$ref": "#/$defs/Envelope.BrandingAccentColor" }, "email": { "type": "object", "additionalProperties": false, "properties": { "from": { "$ref": "#/$defs/Envelope.BrandingEmailFrom" }, "footer": { "$ref": "#/$defs/Envelope.BrandingEmailFooter" }, "logo_position": { "$ref": "#/$defs/Envelope.BrandingEmailLogoPosition" } } } } }, "Envelope.BrandingLogo": { "x-schema-role": "property", "x-schema-direction": "any", "type": [ "string", "null" ], "format": "uri", "title": "Logo", "description": "The URL of the logo image displayed in the header of emails and the signing ceremony.\n\nThe logo must be a PNG file uploaded to the Library. For best results, use an image with a minimum height of 160px, a file size under 100KB, and a transparent background.\n", "maxLength": 2048, "default": null }, "Envelope.DocumentsInput": { "x-schema-role": "property", "x-schema-direction": "input", "type": "array", "title": "Documents", "description": "The documents included in the envelope for recipients to sign. An envelope can contain between 1 and 10 documents.\n\nEach document must be a publicly accessible PDF or DOCX file. Documents can include interactive elements called **places** (such as signature fields, text inputs, and checkboxes) that recipients interact with during the signing ceremony.\n\nDOCX documents also support template data population through the `data` property.", "minItems": 1, "maxItems": 10, "items": { "$ref": "#/$defs/Document.DocumentInput" } }, "Envelope.Label": { "x-schema-role": "property", "x-schema-direction": "any", "title": "Envelope Label", "description": "A custom label for internal identification of the envelope. Labels are not shown to recipients.\n\nUse labels to add internal context that helps your team find and manage envelopes. Unlike the `title` (which recipients see), the label is for your use only. Labels can be updated at any time via the Update Envelope endpoint.\n", "type": [ "string", "null" ], "minLength": 1, "maxLength": 500, "default": null }, "Envelope.Language": { "x-schema-role": "property", "x-schema-direction": "any", "type": "string", "title": "Language", "enum": [ "en", "es", "fr", "it", "pt", "de", "zh", "hu", "nl" ], "description": "The language used for the signing ceremony, recipient emails, and the audit log in deliverables.\n\nSupported languages: `en` (English), `es` (Spanish), `fr` (French), `it` (Italian), `pt` (Portuguese), `de` (German), `zh` (Chinese Simplified), `hu` (Hungarian), `nl` (Dutch).\n\nIf not specified, the account's default language will be used instead.\n" }, "Envelope.Message": { "x-schema-role": "property", "x-schema-direction": "any", "type": [ "string", "null" ], "title": "Envelope Message", "description": "A custom message included in the signing request emails sent to recipients. Use this to provide context about what is being signed.\n\nThe message supports a subset of Markdown formatting:\n- `**bold**` for bold text\n- `*italic*` for italic text\n- `\\n\\n` for paragraph breaks", "minLength": 1, "maxLength": 2000, "default": null }, "Envelope.Metadata": { "x-schema-role": "property", "x-schema-direction": "any", "type": "object", "title": "Envelope Metadata", "description": "Set of key-value pairs to store additional information about the envelope. Use metadata to attach internal reference IDs, tracking numbers, or other data that connects envelopes to your systems.\n\nMetadata is included in all API responses and webhook payloads (in the `data.envelope_metadata` field), making it useful for correlating events with your records.\n\nUp to 10 keys are allowed. Keys can be up to 32 characters (letters, digits, and underscores). Values can be up to 1,000 characters.\n\nUse metadata only for ordinary business identifiers that are appropriate to store with an envelope.\n", "unevaluatedProperties": false, "maxProperties": 10, "default": {}, "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 1000 }, "propertyNames": { "type": "string", "pattern": "^[a-zA-Z0-9_]*$", "minLength": 1, "maxLength": 32 } }, "Envelope.RecipientsInput": { "x-schema-role": "property", "x-schema-direction": "input", "type": "array", "title": "Recipients", "description": "The recipients who will participate in the envelope's signing process. An envelope can have between 1 and 10 recipients.\n\nFour recipient types are supported:\n\n- **signer** -- Signs the documents.\n- **preparer** -- Fills in fields before signers receive the documents.\n- **approver** -- Reviews and approves the documents without signing.\n- **automatic_signer** -- Has their signature applied automatically.\n\nThe order in which recipients act depends on the envelope's `routing` setting. With `sequential` routing (the default), recipients act one at a time in order. With `parallel` routing, all recipients act at the same time.", "minItems": 1, "maxItems": 10, "items": { "$ref": "#/$defs/Recipient.RecipientInput" } }, "Envelope.Routing": { "x-schema-role": "property", "x-schema-direction": "any", "title": "Envelope Routing", "description": "Controls the order in which recipients receive and act on the envelope.\n\n- `sequential` -- Recipients receive the envelope one at a time, in the order listed. Each recipient must complete their part before the next one is notified. Subsequent recipients can see signatures and data from those who acted before them.\n- `parallel` -- All recipients receive the envelope at the same time and can act in any order.\n\nDefaults to `sequential` if not specified.\n", "type": "string", "default": "sequential", "enum": [ "sequential", "parallel" ] }, "Envelope.SenderEmail": { "x-schema-role": "property", "x-schema-direction": "any", "type": "string", "format": "email", "title": "Sender Email", "description": "The email address of the sender, shown to recipients for reference.\n\nIf not specified, the account's default sender email is used.\n", "maxLength": 320 }, "Envelope.SenderInput": { "x-schema-role": "property", "x-schema-direction": "input", "type": "object", "additionalProperties": false, "title": "Envelope Sender", "description": "The sender of the envelope. Sender information appears in the emails sent to recipients, identifying who initiated the signing request.\n\nIf omitted, the account's default sender name and email will be used.", "properties": { "name": { "$ref": "#/$defs/Envelope.SenderName" }, "email": { "$ref": "#/$defs/Envelope.SenderEmail" }, "organization": { "$ref": "#/$defs/Envelope.SenderOrganization" } } }, "Envelope.SenderName": { "x-schema-role": "property", "x-schema-direction": "any", "type": "string", "title": "Sender Name", "description": "The name of the sender, displayed to recipients in emails and the signing ceremony.\n\nIf not specified, the account's default sender name is used.\n", "minLength": 1, "maxLength": 500 }, "Envelope.SenderOrganization": { "x-schema-role": "property", "x-schema-direction": "any", "type": [ "string", "null" ], "title": "Sender Organization", "description": "The organization name of the sender. Displayed to recipients alongside the sender's name and email.\n", "minLength": 1, "maxLength": 500, "default": null }, "Envelope.TimestampFormat": { "x-schema-role": "property", "x-schema-direction": "any", "type": "string", "title": "Timestamp Format", "description": "The date and time format used for timestamps in the deliverable's audit log. Uses MomentJS format tokens (e.g., `MM/DD/YYYY HH:mm:ss`).\n\nIf not specified, the account's default timestamp format is used.\n" }, "Envelope.Timezone": { "x-schema-role": "property", "x-schema-direction": "any", "type": "string", "title": "Time Zone", "description": "The time zone applied to timestamps in the deliverable's audit log. Must be a valid IANA Time Zone Database identifier (e.g., `America/New_York`, `Europe/London`).\n\nIf not specified, the account's default timezone is used.\n" }, "Envelope.Title": { "x-schema-role": "property", "x-schema-direction": "any", "type": "string", "title": "Envelope Title", "description": "The title of the envelope, displayed to recipients in emails and the signing ceremony.\n\nChoose a clear title that helps recipients understand what they are signing. For an internal description that will not be shown to recipients, use the `label` property instead.\n", "minLength": 1, "maxLength": 500 }, "Envelope.Topic": { "x-schema-role": "property", "x-schema-direction": "any", "title": "Envelope Topic", "description": "A tag used to classify the envelope. Topics can be used to filter webhook notifications and query envelopes.\n\nMust start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters.\n", "type": "string", "pattern": "^[a-z][a-z0-9_]*$", "minLength": 1, "maxLength": 32 }, "Envelope.Topics": { "x-schema-role": "property", "x-schema-direction": "any", "title": "Envelope Topics", "description": "Tags used to classify and filter envelopes. Up to 10 topics can be assigned per envelope.\n\nTopics enable two key workflows: filtering webhook notifications so that specific endpoints only receive events for relevant envelopes, and querying envelopes by topic through the List Envelopes endpoint.\n", "type": "array", "maxItems": 10, "default": [], "items": { "$ref": "#/$defs/Envelope.Topic" } }, "Place.BoxCount": { "x-schema-role": "property", "x-schema-direction": "any", "title": "Box Count", "type": [ "number", "null" ], "description": "The number of individual character boxes to display. Each box accepts a single character. Common values include 5 (ZIP code), 6 (verification code), and other short business identifiers. Set to `null` to omit.", "minimum": 1, "maximum": 100, "default": null }, "Place.BoxedTextInputPlaceInput": { "x-schema-role": "model", "x-schema-direction": "input", "title": "Boxed Text Input Place", "description": "A **boxed text input place** displays individual character boxes where a recipient enters text one character per box. This is useful for structured data like verification codes, phone numbers, or ZIP codes.\n\nBoxed text input places are available in envelopes with sequential signing. The `box_count` property controls how many character boxes are displayed.\n\nUse `capture_as` to store the entered text in the envelope's captures for later retrieval.\n", "type": "object", "additionalProperties": false, "properties": { "key": { "$ref": "#/$defs/Place.Key" }, "type": { "allOf": [ { "$ref": "#/$defs/Place.Type" }, { "const": "boxed_text_input" } ] }, "recipient_key": { "$ref": "#/$defs/Place.RecipientKey" }, "requirement": { "allOf": [ { "$ref": "#/$defs/Place.Requirement" }, { "default": "required" } ] }, "font_size": { "$ref": "#/$defs/Place.TextInputFontSize" }, "height": { "$ref": "#/$defs/Place.TextInputHeight" }, "width": { "$ref": "#/$defs/Place.TextInputWidth" }, "box_count": { "$ref": "#/$defs/Place.BoxCount" }, "prompt": { "$ref": "#/$defs/Place.Prompt" }, "hint": { "$ref": "#/$defs/Place.Hint" }, "capture_as": { "$ref": "#/$defs/Place.CaptureAs" } }, "required": [ "key", "type", "recipient_key", "font_size", "width", "height" ] }, "Place.CaptureAs": { "x-schema-role": "property", "x-schema-direction": "any", "title": "Capture As", "description": "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. Set to `null` to disable capture.", "type": [ "string", "null" ], "pattern": "^[a-z][a-z0-9_]*$", "minLength": 1, "maxLength": 32, "default": null }, "Place.CheckboxHeight": { "x-schema-role": "property", "x-schema-direction": "any", "title": "Checkbox Height", "type": "number", "default": 20, "minimum": 8, "maximum": 40, "description": "The height of the checkbox in points (1 point = 1/72 inch). The width equals the height." }, "Place.CheckboxPlaceInput": { "x-schema-role": "model", "x-schema-direction": "input", "title": "Checkbox Place", "description": "A **checkbox place** marks a location on a document where a recipient checks or unchecks a box.\n\nCheckbox places are available in envelopes with sequential signing. The `symbol` property controls whether a checkmark or an X is displayed when checked. Set `requirement` to `required` to force the recipient to check the box before completing their action.\n\nUse `capture_as` to store the checkbox value in the envelope's captures for later retrieval.\n", "type": "object", "additionalProperties": false, "properties": { "key": { "$ref": "#/$defs/Place.Key" }, "type": { "allOf": [ { "$ref": "#/$defs/Place.Type" }, { "const": "checkbox" } ] }, "requirement": { "allOf": [ { "$ref": "#/$defs/Place.Requirement" }, { "default": "optional" } ] }, "recipient_key": { "$ref": "#/$defs/Place.RecipientKey" }, "symbol": { "$ref": "#/$defs/Place.CheckboxSymbol" }, "height": { "$ref": "#/$defs/Place.CheckboxHeight" }, "capture_as": { "$ref": "#/$defs/Place.CaptureAs" } }, "required": [ "key", "type", "recipient_key" ] }, "Place.CheckboxSymbol": { "x-schema-role": "property", "x-schema-direction": "any", "title": "Checkbox Symbol", "description": "The symbol displayed when the checkbox is checked. `check` shows a checkmark. `xmark` shows an X.", "type": "string", "enum": [ "check", "xmark" ], "default": "check" }, "Place.DateFormat": { "x-schema-role": "property", "x-schema-direction": "any", "type": "string", "title": "Date Format", "description": "The date and time format string using Moment.js syntax. Common formats include `D MMM YYYY` (31 Dec 2025), `YYYY-MM-DD` (2025-12-31), `MM/DD/YYYY` (12/31/2025), and `MMMM D, YYYY` (December 31, 2025). You can include time with `DD/MM/YYYY HH:mm`.", "default": "D MMM YYYY" }, "Place.DropdownPlaceBehavior": { "x-schema-role": "property", "x-schema-direction": "any", "title": "Dropdown Behavior", "description": "Specifies the behavior of the dropdown place. If omitted, the default is auto.\n\nWhen set to auto, the behavior is determined by the number of options:\n- `select` if there are 10 or fewer options\n- `combobox` if there are more than 10 options", "type": "string", "enum": [ "auto", "select", "combobox" ], "default": "auto" }, "Place.DropdownPlaceCustomOptions": { "x-schema-role": "property", "x-schema-direction": "any", "title": "Custom Options", "description": "A custom list of options for the dropdown. Each option has a label displayed to the recipient and an optional value that is captured when selected. If no value is provided, the label is used as the captured value.", "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "description": "The text displayed to the recipient for this option." }, "value": { "type": "string", "description": "The value captured when the recipient selects this option. If omitted, the label is used as the value." } }, "required": [ "label" ] } }, "Place.DropdownPlaceDefault": { "x-schema-role": "property", "x-schema-direction": "any", "title": "Default Option", "description": "This property specifies the option that will be selected by default when the place is displayed. Its value is first matched against the label of each item in the options array; if no match is found, it is matched against the value of each item.\n\nIf no match is found, a validation error is returned.", "type": [ "string", "null" ], "default": null }, "Place.DropdownPlaceInput": { "x-schema-role": "model", "x-schema-direction": "input", "title": "Dropdown Place", "description": "A **dropdown place** marks a location on a document where a recipient selects from a list of options.\n\nDropdown places are available in envelopes with sequential signing. Options can be a custom array of label-value pairs or a predefined set such as `us_states_names` or `world_countries_names`.\n\nThe `behavior` property controls how the dropdown is displayed. When set to `auto`, it renders as a standard dropdown for 10 or fewer options and as a searchable combobox for more than 10 options.\n\nUse `capture_as` to store the selected value in the envelope's captures for later retrieval.\n", "type": "object", "additionalProperties": false, "properties": { "key": { "$ref": "#/$defs/Place.Key" }, "type": { "allOf": [ { "$ref": "#/$defs/Place.Type" }, { "const": "dropdown" } ] }, "recipient_key": { "$ref": "#/$defs/Place.RecipientKey" }, "requirement": { "allOf": [ { "$ref": "#/$defs/Place.Requirement" }, { "default": "required" } ] }, "prompt": { "$ref": "#/$defs/Place.Prompt" }, "hint": { "$ref": "#/$defs/Place.Hint" }, "capture_as": { "$ref": "#/$defs/Place.CaptureAs" }, "options": { "$ref": "#/$defs/Place.DropdownPlaceOptions" }, "default": { "$ref": "#/$defs/Place.DropdownPlaceDefault" }, "behavior": { "$ref": "#/$defs/Place.DropdownPlaceBehavior" }, "font_size": { "$ref": "#/$defs/Place.TextInputFontSize" }, "width": { "$ref": "#/$defs/Place.TextInputWidth" } }, "required": [ "key", "type", "recipient_key", "options" ] }, "Place.DropdownPlaceOptions": { "x-schema-role": "property", "x-schema-direction": "any", "description": "The options available in the dropdown. Can be a custom array of label-value pairs or a predefined set such as country names or US state codes.", "oneOf": [ { "$ref": "#/$defs/Place.DropdownPlaceCustomOptions" }, { "$ref": "#/$defs/Place.DropdownPlacePredefinedOptions" } ] }, "Place.DropdownPlacePredefinedOptions": { "x-schema-role": "property", "x-schema-direction": "any", "title": "Predefined Options", "description": "A built-in set of options for the dropdown. `world_countries_names` provides full country names. `world_countries_2_letter_codes` and `world_countries_3_letter_codes` provide ISO country codes. `world_countries_numeric_codes` provides numeric country codes. `us_states_names` provides full US state names. `us_states_2_letter_codes` provides two-letter US state codes.", "type": "string", "enum": [ "world_countries_names", "world_countries_2_letter_codes", "world_countries_3_letter_codes", "world_countries_numeric_codes", "us_states_names", "us_states_2_letter_codes" ] }, "Place.EnvelopeDatePlaceInput": { "x-schema-role": "model", "x-schema-direction": "input", "title": "Envelope Completed Date Place", "description": "An **envelope completed date place** displays the date and time when the envelope was completed. The envelope is completed when all recipients have finished their actions.\n\nThis place does not require a `recipient_key` because it applies to the envelope as a whole. Use `date_format` to control how the date is formatted using Moment.js syntax.\n", "type": "object", "additionalProperties": false, "properties": { "key": { "$ref": "#/$defs/Place.Key" }, "type": { "allOf": [ { "$ref": "#/$defs/Place.Type" }, { "const": "envelope_completed_date" } ] }, "date_format": { "$ref": "#/$defs/Place.DateFormat" }, "font_size": { "$ref": "#/$defs/Place.FontSize" } }, "required": [ "key", "type" ] }, "Place.FontColor": { "x-schema-role": "property", "x-schema-direction": "any", "title": "Place Font Color", "description": "The font color for a text-based place. Must be a six-digit hex color code with a leading `#`.", "type": "string", "pattern": "^#[a-fA-F0-9]{6}$", "default": "#000000" }, "Place.FontSize": { "x-schema-role": "property", "x-schema-direction": "any", "title": "Place Font Size", "description": "The font size in points for a text-based place. One point equals 1/72 of an inch.", "type": "number", "minimum": 1, "maximum": 144, "default": 12 }, "Place.Hint": { "x-schema-role": "property", "x-schema-direction": "any", "title": "Hint", "description": "A tooltip displayed to the recipient when they hover over or focus on the place. Use this to provide guidance about what to enter. Set to `null` for no hint.", "type": [ "string", "null" ], "minLength": 1, "maxLength": 100, "default": null }, "Place.InitialsHeight": { "x-schema-role": "property", "x-schema-direction": "any", "title": "Initials Place Height", "type": "number", "description": "The height of the initials place in points (1 point = 1/72 inch). The width equals the height.", "minimum": 20, "maximum": 60, "default": 60 }, "Place.InitialsPlaceInput": { "x-schema-role": "model", "x-schema-direction": "input", "title": "Initials Place", "description": "An **initials place** marks a location on a document where a recipient enters their initials.\n\nEach initials place is linked to a specific recipient through the `recipient_key`. A single recipient can have multiple initials places across different pages of a document.\n\nThe width equals the height.\n", "type": "object", "additionalProperties": false, "properties": { "key": { "$ref": "#/$defs/Place.Key" }, "type": { "allOf": [ { "$ref": "#/$defs/Place.Type" }, { "const": "initials" } ] }, "recipient_key": { "$ref": "#/$defs/Place.RecipientKey" }, "height": { "$ref": "#/$defs/Place.InitialsHeight" } }, "required": [ "key", "type", "recipient_key" ] }, "Place.Key": { "x-schema-role": "property", "x-schema-direction": "any", "title": "Place Key", "description": "A unique identifier for a place within a document. Used to match a place to its position, either through a `[[place_key]]` placeholder in the document or a fixed position entry. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores.", "type": "string", "pattern": "^[a-z][a-z0-9_]*$", "minLength": 1, "maxLength": 32 }, "Place.MultiLineTextInputLineCount": { "x-schema-role": "property", "x-schema-direction": "any", "title": "Line Count", "description": "The number of visible text lines in the multi-line input field. Determines the vertical size of the field.", "type": "integer", "minimum": 1, "maximum": 100 }, "Place.MultiLineTextInputLineHeight": { "x-schema-role": "property", "x-schema-direction": "any", "title": "Line Height", "description": "The vertical spacing between lines in points (1 point = 1/72 inch). Must be greater than or equal to `font_size`.", "type": "number", "minimum": 6, "maximum": 72, "default": 12 }, "Place.MultiLineTextInputPlaceInput": { "x-schema-role": "model", "x-schema-direction": "input", "title": "Multi-Line Text Input Place", "description": "A **multi-line text input place** marks a location on a document where a recipient enters text that spans multiple lines. This is useful for comments, addresses, and longer descriptions.\n\nMulti-line text input places are available in envelopes with sequential signing. The `line_count` property sets the number of visible lines. The `line_height` property controls the vertical spacing between lines and must be greater than or equal to `font_size`.\n\nUse `capture_as` to store the entered text in the envelope's captures for later retrieval.\n", "type": "object", "additionalProperties": false, "properties": { "key": { "$ref": "#/$defs/Place.Key" }, "type": { "allOf": [ { "$ref": "#/$defs/Place.Type" }, { "const": "multiline_text_input" } ] }, "recipient_key": { "$ref": "#/$defs/Place.RecipientKey" }, "requirement": { "allOf": [ { "$ref": "#/$defs/Place.Requirement" }, { "default": "required" } ] }, "prompt": { "$ref": "#/$defs/Place.Prompt" }, "hint": { "$ref": "#/$defs/Place.Hint" }, "capture_as": { "$ref": "#/$defs/Place.CaptureAs" }, "font_size": { "$ref": "#/$defs/Place.TextInputFontSize" }, "width": { "$ref": "#/$defs/Place.TextInputWidth" }, "line_count": { "$ref": "#/$defs/Place.MultiLineTextInputLineCount" }, "line_height": { "$ref": "#/$defs/Place.MultiLineTextInputLineHeight" } }, "required": [ "key", "type", "recipient_key", "width", "line_count" ] }, "Place.PlaceInput": { "x-schema-role": "model", "x-schema-direction": "input", "title": "Place", "description": "A **place** is a location on a document where a recipient performs an action or where information is displayed. Places define signature fields, input areas, and auto-filled values at specific positions in documents.\n\nEach place has a **type** that determines its behavior. The `type` field acts as a discriminator across the following place types:\n\n- **signature** -- A recipient draws or types their signature.\n- **initials** -- A recipient enters their initials.\n- **checkbox** -- A recipient checks or unchecks a box.\n- **text_input** -- A recipient types free-form text.\n- **boxed_text_input** -- A recipient enters text into individual character boxes.\n- **multiline_text_input** -- A recipient enters text across multiple lines.\n- **dropdown** -- A recipient selects from a list of options.\n- **radio_group** -- A recipient selects exactly one option from a set of scattered choices sharing a group.\n- **text** -- A read-only text value displayed on the document.\n- **envelope_completed_date** -- The date the envelope was completed.\n- **recipient_completed_date** -- The date the recipient completed their action.\n- **recipient_name** -- The recipient's name.\n- **recipient_email** -- The recipient's email address.\n\n### Positioning\n\nPlaces can be positioned on a document in two ways:\n\n- **Placeholder text** -- Embed `[[place_key]]` in the document. The place appears where the placeholder is found.\n- **Fixed position** -- Specify exact coordinates using page number, top, and left values measured in points (1 point = 1/72 inch).\n", "oneOf": [ { "$ref": "#/$defs/Place.SignaturePlaceInput" }, { "$ref": "#/$defs/Place.InitialsPlaceInput" }, { "$ref": "#/$defs/Place.RecipientDatePlaceInput" }, { "$ref": "#/$defs/Place.EnvelopeDatePlaceInput" }, { "$ref": "#/$defs/Place.RecipientNamePlaceInput" }, { "$ref": "#/$defs/Place.RecipientEmailPlaceInput" }, { "$ref": "#/$defs/Place.TextPlaceInput" }, { "$ref": "#/$defs/Place.TextInputPlaceInput" }, { "$ref": "#/$defs/Place.BoxedTextInputPlaceInput" }, { "$ref": "#/$defs/Place.MultiLineTextInputPlaceInput" }, { "$ref": "#/$defs/Place.DropdownPlaceInput" }, { "$ref": "#/$defs/Place.RadioGroupPlaceInput" }, { "$ref": "#/$defs/Place.CheckboxPlaceInput" } ] }, "Place.Prompt": { "x-schema-role": "property", "x-schema-direction": "any", "title": "Prompt", "description": "Placeholder text displayed inside the input field before the recipient types. Disappears when the recipient starts entering text. Set to `null` for no prompt.", "type": [ "string", "null" ], "minLength": 1, "maxLength": 100, "default": null }, "Place.RadioGroupHeight": { "x-schema-role": "property", "x-schema-direction": "any", "title": "Radio Group Height", "type": "number", "default": 20, "minimum": 8, "maximum": 40, "description": "The height of each radio option in points (1 point = 1/72 inch). The width equals the height." }, "Place.RadioGroupMemberKey": { "x-schema-role": "property", "x-schema-direction": "any", "title": "Radio Group Member Key", "description": "The key of a single positioned radio_group option. Each option expands into its own place row keyed `group_key:option_value` (for example `billing_cycle:monthly`).", "type": "string", "pattern": "^[a-z][a-z0-9_]*(:[a-z0-9_]+)?$", "minLength": 1, "maxLength": 63 }, "Place.RadioGroupPlaceDefault": { "x-schema-role": "property", "x-schema-direction": "any", "title": "Default Option", "description": "The option selected by default when the place is displayed. Its value must match the `value` of one of the options in the group.\n\nIf no match is found, a validation error is returned.", "type": [ "string", "null" ], "minLength": 1, "maxLength": 32, "default": null }, "Place.RadioGroupPlaceInput": { "x-schema-role": "model", "x-schema-direction": "input", "title": "Radio Group Place", "description": "A **radio group place** marks the options of a single-choice question scattered across a document, where a recipient selects exactly one option from the group.\n\nUnlike a dropdown, each option is a separate mark placed independently on the document. All options that share a `group` are mutually exclusive: selecting one clears the others. The `symbol` property controls how a selected option is drawn (`fill`, `check`, or `xmark`), and `shape` controls the geometry of the control (`circle` or `square`). A `fill` symbol takes the control's shape.\n\n### Options\n\nThe `options` array lists the allowed values for the group. Each option carries a `value` that is captured when it is selected. Use `capture_as` to store the selected value in the envelope's captures; the captured value equals the `value` of the option the recipient chose.\n\nProvide `default` to preselect an option; its value must match one of the option `value`s.\n\n### Positioning\n\nOptions are positioned individually, not as a single block. Address each option with a `group_key:value` key, either through a `[[group_key:value]]` placeholder in the document or a fixed position whose `place_key` is `group_key:value`.\n\nFor example, a `billing_cycle` group with options `monthly` and `annual` is positioned with the placeholders `[[billing_cycle:monthly]]` and `[[billing_cycle:annual]]` (or the equivalent fixed positions `billing_cycle:monthly` and `billing_cycle:annual`). The recipient selects exactly one, and its `value` (`monthly` or `annual`) is stored under `capture_as`.\n\nRadio group places are available in envelopes with sequential signing.\n", "type": "object", "additionalProperties": false, "properties": { "key": { "$ref": "#/$defs/Place.Key" }, "type": { "allOf": [ { "$ref": "#/$defs/Place.Type" }, { "const": "radio_group" } ] }, "recipient_key": { "$ref": "#/$defs/Place.RecipientKey" }, "options": { "$ref": "#/$defs/Place.RadioGroupPlaceOptions" }, "symbol": { "$ref": "#/$defs/Place.RadioGroupSymbol" }, "shape": { "$ref": "#/$defs/Place.RadioGroupShape" }, "requirement": { "allOf": [ { "$ref": "#/$defs/Place.Requirement" }, { "default": "required" } ] }, "default": { "$ref": "#/$defs/Place.RadioGroupPlaceDefault" }, "capture_as": { "$ref": "#/$defs/Place.CaptureAs" }, "height": { "$ref": "#/$defs/Place.RadioGroupHeight" } }, "required": [ "key", "type", "recipient_key", "options" ] }, "Place.RadioGroupPlaceOptions": { "x-schema-role": "property", "x-schema-direction": "any", "title": "Radio Group Options", "description": "The set of allowed options in the group. Each option carries a `value` that is captured under `capture_as` when that option is selected. Options are positioned individually on the document using a `group_key:value` key.", "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "description": "The value captured when the recipient selects this option. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores.", "pattern": "^[a-z][a-z0-9_]*$", "minLength": 1, "maxLength": 32 } }, "required": [ "value" ] } }, "Place.RadioGroupShape": { "x-schema-role": "property", "x-schema-direction": "any", "title": "Radio Group Shape", "description": "The geometry of the control. `circle` draws a round radio button. `square` draws a box, matching documents that print square options. When `symbol` is `fill`, the stamped mark takes this shape.", "type": "string", "enum": [ "circle", "square" ], "default": "circle" }, "Place.RadioGroupSymbol": { "x-schema-role": "property", "x-schema-direction": "any", "title": "Radio Group Symbol", "description": "The symbol drawn when an option in the group is selected. `fill` draws a solid mark in the control's `shape`. `check` shows a checkmark. `xmark` shows an X.", "type": "string", "enum": [ "fill", "check", "xmark" ], "default": "fill" }, "Place.RecipientDatePlaceInput": { "x-schema-role": "model", "x-schema-direction": "input", "title": "Recipient Completed Date Place", "description": "A **recipient completed date place** displays the date and time when a specific recipient completed their action on the envelope.\n\nEach recipient date place is linked to a specific recipient through the `recipient_key`. Use `date_format` to control how the date is formatted using Moment.js syntax.\n", "type": "object", "additionalProperties": false, "properties": { "key": { "$ref": "#/$defs/Place.Key" }, "type": { "allOf": [ { "$ref": "#/$defs/Place.Type" }, { "const": "recipient_completed_date" } ] }, "recipient_key": { "$ref": "#/$defs/Place.RecipientKey" }, "date_format": { "$ref": "#/$defs/Place.DateFormat" }, "font_size": { "$ref": "#/$defs/Place.FontSize" } }, "required": [ "key", "type", "recipient_key" ] }, "Place.RecipientEmailPlaceInput": { "x-schema-role": "model", "x-schema-direction": "input", "title": "Recipient Email Place", "description": "A **recipient email place** displays a recipient's email address at a specific location on the document. The email address is inserted automatically based on the recipient linked through the `recipient_key`.\n\nThis place is read-only and does not require any action from the recipient.\n", "type": "object", "additionalProperties": false, "properties": { "key": { "$ref": "#/$defs/Place.Key" }, "type": { "allOf": [ { "$ref": "#/$defs/Place.Type" }, { "const": "recipient_email" } ] }, "recipient_key": { "$ref": "#/$defs/Place.RecipientKey" }, "font_size": { "$ref": "#/$defs/Place.FontSize" } }, "required": [ "key", "type", "recipient_key" ] }, "Place.RecipientKey": { "x-schema-role": "property", "x-schema-direction": "any", "allOf": [ { "$ref": "#/$defs/Recipient.Key" }, { "title": "Recipient Key", "description": "The key of the recipient assigned to this place. Must match one of the `recipient.key` values in the envelope's recipient list." } ] }, "Place.RecipientNamePlaceInput": { "x-schema-role": "model", "x-schema-direction": "input", "title": "Recipient Name Place", "description": "A **recipient name place** displays a recipient's name at a specific location on the document. The name is inserted automatically based on the recipient linked through the `recipient_key`.\n\nThis place is read-only and does not require any action from the recipient.\n", "type": "object", "additionalProperties": false, "properties": { "key": { "$ref": "#/$defs/Place.Key" }, "type": { "allOf": [ { "$ref": "#/$defs/Place.Type" }, { "const": "recipient_name" } ] }, "recipient_key": { "$ref": "#/$defs/Place.RecipientKey" }, "font_size": { "$ref": "#/$defs/Place.FontSize" } }, "required": [ "key", "type", "recipient_key" ] }, "Place.Requirement": { "x-schema-role": "property", "x-schema-direction": "any", "title": "Requirement", "description": "Whether the recipient must complete this place before finishing their action. When set to `required`, the recipient cannot proceed without filling in or checking the place. When set to `optional`, the recipient may skip it.", "type": "string", "enum": [ "required", "optional" ] }, "Place.SignatureHeight": { "x-schema-role": "property", "x-schema-direction": "any", "title": "Signature Place Height", "type": "number", "description": "The height of the signature place in points (1 point = 1/72 inch). The width is automatically calculated using a 5:2 ratio based on this height.", "minimum": 20, "maximum": 60, "default": 60 }, "Place.SignaturePlaceInput": { "x-schema-role": "model", "x-schema-direction": "input", "title": "Signature Place", "description": "A **signature place** marks a location on a document where a recipient draws or types their signature.\n\nEach signature place is linked to a specific recipient through the `recipient_key`. A single recipient can have multiple signature places across different pages of a document.\n\nThe width is automatically calculated using a 5:2 ratio based on the height.\n", "type": "object", "additionalProperties": false, "properties": { "key": { "$ref": "#/$defs/Place.Key" }, "type": { "allOf": [ { "$ref": "#/$defs/Place.Type" }, { "const": "signature" } ] }, "recipient_key": { "$ref": "#/$defs/Place.RecipientKey" }, "height": { "$ref": "#/$defs/Place.SignatureHeight" } }, "required": [ "key", "type", "recipient_key" ] }, "Place.TextInputFontSize": { "x-schema-role": "property", "x-schema-direction": "any", "title": "Font Size", "description": "The font size in points for this input place. One point equals 1/72 of an inch.", "type": "number", "minimum": 6, "maximum": 12, "default": 12 }, "Place.TextInputFormat": { "x-schema-role": "property", "x-schema-direction": "any", "title": "Text Input Format", "description": "Specifies the validation to apply to the text input, such as requiring a specific format (e.g., email, US zipcode), a custom regular expression, or no validation at all.\n", "anyOf": [ { "type": "string", "enum": [ "email", "zipcode-us" ], "title": "Predefined Format", "description": "A predefined format that must match the input text." }, { "type": "string", "pattern": "^/.*?/$", "minLength": 1, "maxLength": 100, "title": "Custom Format", "description": "A regular expression that must match the input text." }, { "type": "null", "title": "No Validation", "description": "No validation is performed on the input text." } ], "default": null }, "Place.TextInputFormatMessage": { "x-schema-role": "property", "x-schema-direction": "any", "title": "Format Message", "description": "A message displayed to the recipient when their input does not match the specified `format`. Use this to explain what format is expected. Set to `null` to use the default validation message.", "type": [ "string", "null" ], "minLength": 1, "maxLength": 100, "default": null }, "Place.TextInputHeight": { "x-schema-role": "property", "x-schema-direction": "any", "title": "Height", "description": "The height of the input field in points (1 point = 1/72 inch).", "type": "number", "minimum": 6, "maximum": 60 }, "Place.TextInputPlaceInput": { "x-schema-role": "model", "x-schema-direction": "input", "title": "Text Input Place", "description": "A **text input place** marks a location on a document where a recipient types free-form text.\n\nText input places are available in envelopes with sequential signing. Use `prompt` to display placeholder text inside the field and `hint` to show a tooltip on hover.\n\nInput validation is controlled through the `format` property. You can use predefined formats like `email` or `zipcode-us`, or provide a custom regular expression. Set `format_message` to display a message when validation fails.\n\nUse `capture_as` to store the entered text in the envelope's captures for later retrieval.\n", "type": "object", "additionalProperties": false, "properties": { "key": { "$ref": "#/$defs/Place.Key" }, "type": { "allOf": [ { "$ref": "#/$defs/Place.Type" }, { "const": "text_input" } ] }, "recipient_key": { "$ref": "#/$defs/Place.RecipientKey" }, "requirement": { "allOf": [ { "$ref": "#/$defs/Place.Requirement" }, { "default": "required" } ] }, "prompt": { "$ref": "#/$defs/Place.Prompt" }, "hint": { "$ref": "#/$defs/Place.Hint" }, "capture_as": { "$ref": "#/$defs/Place.CaptureAs" }, "format": { "$ref": "#/$defs/Place.TextInputFormat" }, "format_message": { "$ref": "#/$defs/Place.TextInputFormatMessage" }, "font_size": { "$ref": "#/$defs/Place.TextInputFontSize" }, "width": { "$ref": "#/$defs/Place.TextInputWidth" } }, "required": [ "key", "type", "recipient_key" ] }, "Place.TextInputWidth": { "x-schema-role": "property", "x-schema-direction": "any", "title": "Width", "description": "The width of the input field in points (1 point = 1/72 inch). The field may expand beyond this width during typing.", "type": "number", "minimum": 30, "maximum": 540, "default": 30 }, "Place.TextPlaceInput": { "x-schema-role": "model", "x-schema-direction": "input", "title": "Text Place", "description": "A **text place** inserts a read-only text value at a specific location on a document. It is not interactive and does not require a recipient.\n\nText places are useful for pre-filling information such as company names, reference numbers, or dates before the signing process begins.\n", "type": "object", "additionalProperties": false, "properties": { "key": { "$ref": "#/$defs/Place.Key" }, "type": { "allOf": [ { "$ref": "#/$defs/Place.Type" }, { "const": "text" } ] }, "value": { "$ref": "#/$defs/Place.TextValue" }, "font_size": { "$ref": "#/$defs/Place.FontSize" }, "font_color": { "$ref": "#/$defs/Place.FontColor" } }, "required": [ "key", "type", "value" ] }, "Place.TextValue": { "x-schema-role": "property", "x-schema-direction": "any", "title": "Text Value", "description": "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.", "type": "string", "minLength": 1, "maxLength": 1000 }, "Place.Type": { "x-schema-role": "property", "x-schema-direction": "any", "title": "Place Type", "description": "The type of place. Determines the behavior and available properties. `signature` -- recipient draws or types a signature. `initials` -- recipient enters their initials. `checkbox` -- recipient checks or unchecks a box. `text_input` -- recipient types free-form text. `boxed_text_input` -- recipient enters text into individual character boxes. `multiline_text_input` -- recipient enters text across multiple lines. `dropdown` -- recipient selects from a list of options. `radio_group` -- recipient selects exactly one option from a set of scattered choices sharing a group. `text` -- read-only text value placed on the document. `recipient_completed_date` -- date the recipient completed their action. `envelope_completed_date` -- date the envelope was completed. `recipient_name` -- the recipient's name. `recipient_email` -- the recipient's email address.", "type": "string", "enum": [ "signature", "initials", "recipient_completed_date", "envelope_completed_date", "recipient_name", "recipient_email", "text", "text_input", "boxed_text_input", "multiline_text_input", "dropdown", "radio_group", "checkbox" ] }, "Recipient.ApproverInput": { "x-schema-role": "model", "x-schema-direction": "input", "title": "Approver", "description": "An **approver** is a recipient who reviews and approves documents without signing them. Approvers can fill in input fields such as text boxes and checkboxes, but they cannot add signatures or initials.\n\nUse approvers for workflows that require review or authorization before documents are sent to signers — for example, a manager approving a contract before the client signs it.\n\nApprover actions are not recorded in the audit log.\n\n### Delivery\n\nThe `delivery_type` controls whether SignatureAPI emails the completed deliverable to the approver. It defaults to `none`. Set it to `email` if you want the approver to receive the deliverable.\n\nThe approver receives an email with the ceremony link when the ceremony uses `email_link` authentication, which is the default. To share the ceremony URL yourself instead, use `custom` authentication.\n", "type": "object", "additionalProperties": false, "properties": { "type": { "allOf": [ { "$ref": "#/$defs/Recipient.Type" }, { "const": "approver" } ] }, "key": { "$ref": "#/$defs/Recipient.Key" }, "email": { "$ref": "#/$defs/Recipient.Email" }, "name": { "$ref": "#/$defs/Recipient.Name" }, "ceremony": { "$ref": "#/$defs/Recipient.CeremonyInput" }, "delivery_type": { "allOf": [ { "$ref": "#/$defs/Recipient.DeliveryType" }, { "default": "none" } ] } }, "required": [ "type", "key", "email", "name" ] }, "Recipient.AutomaticSignerInput": { "x-schema-role": "model", "x-schema-direction": "input", "title": "Automatic Signer", "description": "A person whose signature is applied automatically by the system. No email is sent and no ceremony is created. The `mandate` field records why the initiator is authorized to sign on their behalf.\n", "type": "object", "additionalProperties": false, "properties": { "type": { "allOf": [ { "$ref": "#/$defs/Recipient.Type" }, { "const": "automatic_signer" } ] }, "key": { "$ref": "#/$defs/Recipient.Key" }, "name": { "$ref": "#/$defs/Recipient.Name" }, "signature": { "$ref": "#/$defs/Recipient.PresetSymbolInput" }, "initials": { "$ref": "#/$defs/Recipient.PresetSymbolInput" }, "mandate": { "$ref": "#/$defs/Recipient.Mandate" } }, "required": [ "type", "key", "name", "mandate" ] }, "Recipient.CeremonyInput": { "x-schema-role": "property", "x-schema-direction": "input", "title": "Ceremony", "description": "Configuration for the first ceremony to create for the recipient.\n\nIf not provided, a ceremony with `email_link` authentication is created by default. Use this to set a different authentication method, configure redirects, or enable embedding.\n", "allOf": [ { "$ref": "#/$defs/Ceremony.CeremonyInput" } ] }, "Recipient.DeliveryType": { "x-schema-role": "property", "x-schema-direction": "any", "type": "string", "enum": [ "email", "none" ], "title": "Recipient Delivery Type", "description": "Controls whether SignatureAPI emails the completed deliverable to the recipient once the envelope is finished.\n\n| Type | Description |\n|------|-------------|\n| `email` | SignatureAPI emails the deliverable to the recipient. Default for signers. |\n| `none` | No deliverable email is sent. Your application is responsible for distributing the deliverable. Default for approvers and preparers. |\n" }, "Recipient.Email": { "x-schema-role": "property", "x-schema-direction": "any", "type": "string", "format": "email", "title": "Recipient Email", "description": "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`.\n", "maxLength": 320 }, "Recipient.Key": { "x-schema-role": "property", "x-schema-direction": "any", "title": "Recipient Key", "description": "A user-provided key that identifies a recipient within an envelope. Use the key to reference this recipient when assigning document places.\n\nThe key must start with a lowercase letter and can contain lowercase letters, numbers, and underscores. Maximum 32 characters.\n", "type": "string", "pattern": "^[a-z][a-z0-9_]*$", "minLength": 1, "maxLength": 32 }, "Recipient.Mandate": { "x-schema-role": "property", "x-schema-direction": "any", "title": "Mandate", "description": "A short statement explaining why the initiator is authorized to sign on behalf\nof this person. This string will be shown as-is in the audit log.\n", "type": "string", "minLength": 1, "maxLength": 500 }, "Recipient.Name": { "x-schema-role": "property", "x-schema-direction": "any", "type": "string", "title": "Recipient Name", "description": "The full name of the recipient. Appears in invitation emails and is pre-filled for typed signatures.\n", "minLength": 1, "maxLength": 500 }, "Recipient.PreparerInput": { "x-schema-role": "model", "x-schema-direction": "input", "title": "Preparer", "description": "A **preparer** is a recipient who fills in document fields on behalf of another party. Preparers can complete text fields, checkboxes, and dropdowns, but they cannot add signatures or initials.\n\nUse preparers when someone needs to populate document data before a signer receives the envelope — for example, a sales representative entering pricing or contract terms.\n\nThe values a preparer enters are visible to subsequent recipients in the routing order. Preparer actions are not recorded in the audit log.\n\n### Delivery\n\nThe `delivery_type` controls whether SignatureAPI emails the completed deliverable to the preparer. It defaults to `none`. Set it to `email` if you want the preparer to receive the deliverable.\n\nThe preparer receives an email with the ceremony link when the ceremony uses `email_link` authentication, which is the default. To share the ceremony URL yourself instead, use `custom` authentication.\n", "type": "object", "additionalProperties": false, "properties": { "type": { "allOf": [ { "$ref": "#/$defs/Recipient.Type" }, { "const": "preparer" } ] }, "key": { "$ref": "#/$defs/Recipient.Key" }, "email": { "$ref": "#/$defs/Recipient.Email" }, "name": { "$ref": "#/$defs/Recipient.Name" }, "ceremony": { "$ref": "#/$defs/Recipient.CeremonyInput" }, "delivery_type": { "allOf": [ { "$ref": "#/$defs/Recipient.DeliveryType" }, { "default": "none" } ] } }, "required": [ "type", "key", "email", "name" ] }, "Recipient.PresetSymbolDrawnInput": { "x-schema-role": "model", "x-schema-direction": "input", "title": "Drawn Preset Symbol", "description": "A PNG image referenced by its upload URL.", "type": "object", "additionalProperties": false, "properties": { "type": { "allOf": [ { "$ref": "#/$defs/Recipient.PresetSymbolType" }, { "const": "drawn" } ] }, "url": { "type": "string", "format": "uri", "description": "The URL of an Upload owned by the account of a PNG image. Both temporary uploads\n(created via `POST /v1/uploads`) and permanent uploads (stored via the\nDashboard or via `POST /v1/uploads/{id}/store`) are accepted. The upload\nmust not be expired.\n" } }, "required": [ "type", "url" ] }, "Recipient.PresetSymbolInput": { "x-schema-role": "model", "x-schema-direction": "input", "title": "Preset Symbol", "description": "A symbol (signature or initials) supplied up-front for an automatic signer.\n", "oneOf": [ { "$ref": "#/$defs/Recipient.PresetSymbolDrawnInput" } ] }, "Recipient.PresetSymbolType": { "x-schema-role": "enum", "x-schema-direction": "any", "title": "Preset Symbol Type", "description": "The type of preset symbol.", "type": "string", "enum": [ "drawn" ] }, "Recipient.QualifiedSignerInput": { "x-schema-role": "model", "x-schema-direction": "input", "title": "Qualified Signer", "description": "A **qualified signer** is a recipient who signs with a qualified electronic signature: a signature backed by a qualified certificate issued to the signer by a qualified trust service provider (QTSP) during the ceremony.\n\nThe ceremony works like a signer's — the recipient reviews documents, adopts a signature, and consents — but completion is deferred while the qualified signature is produced and embedded through the trust service provider. The `scheme` selects the legal scheme the signature is produced under, and once the signature has been embedded the `certificate` reports the issued signing certificate.\n\nQualified signers are available on request. Envelopes with qualified signers must use sequential routing, and every non-automatic signing recipient on the envelope must be a qualified signer.\n\n### Delivery\n\nThe `delivery_type` controls whether SignatureAPI emails the completed deliverable to the qualified signer. It defaults to `email`. Set it to `none` to distribute the deliverable yourself.\n\nThe qualified signer receives an email with the ceremony link when the ceremony uses `email_link` authentication, which is the default.\n\n### Signature options\n\nThe `signature_options` array controls how the signer can adopt the visible signature. Options are `typed` (pre-filled with the signer's name) and `drawn` (mouse, stylus, or touchscreen). Both are enabled by default, with `typed` as the first option shown.\n", "type": "object", "additionalProperties": false, "properties": { "type": { "allOf": [ { "$ref": "#/$defs/Recipient.Type" }, { "const": "qualified_signer" } ] }, "key": { "$ref": "#/$defs/Recipient.Key" }, "email": { "$ref": "#/$defs/Recipient.Email" }, "name": { "$ref": "#/$defs/Recipient.Name" }, "ceremony": { "$ref": "#/$defs/Recipient.CeremonyInput" }, "delivery_type": { "allOf": [ { "$ref": "#/$defs/Recipient.DeliveryType" }, { "default": "email" } ] }, "signature_options": { "$ref": "#/$defs/Recipient.SignatureOptions" }, "scheme": { "$ref": "#/$defs/Recipient.SignatureScheme" } }, "required": [ "type", "key", "email", "name", "scheme" ] }, "Recipient.RecipientInput": { "x-schema-role": "model", "x-schema-direction": "input", "title": "Recipient", "description": "A **recipient** is a person who receives an envelope and performs an action on it, such as signing, approving, or preparing documents.\n\nEach recipient has a **type** that determines what they can do:\n\n- **Signer** — signs documents. This is the most common recipient type. Every envelope must have at least one signing recipient.\n- **Approver** — reviews and approves documents without signing them.\n- **Preparer** — fills in document fields before the signer receives them.\n- **Automatic Signer** — the signature is applied automatically by the system.\n\nThe `type` field acts as a discriminator. The properties available on a recipient depend on its type.\n\n### Routing\n\nRecipients are routed in the order they appear in the envelope's `recipients` array. By default, recipients are processed sequentially — each recipient must complete before the next one is notified. Recipients at the same routing position are processed in parallel.\n\n### Lifecycle\n\nA recipient moves through a series of statuses: `pending`, `awaiting`, `sent`, `completed`, `rejected`, `soft_bounced`, `hard_bounced`, `failed`, or `replaced`. See `status` for details on each.\n", "oneOf": [ { "$ref": "#/$defs/Recipient.SignerInput" }, { "$ref": "#/$defs/Recipient.QualifiedSignerInput" }, { "$ref": "#/$defs/Recipient.ApproverInput" }, { "$ref": "#/$defs/Recipient.PreparerInput" }, { "$ref": "#/$defs/Recipient.AutomaticSignerInput" } ] }, "Recipient.SignatureOptions": { "x-schema-role": "property", "x-schema-direction": "any", "title": "Recipient Signature Options", "description": "The signature methods available to the signer. Only applies to signers. The first option in the array is shown as the default.\n\n| Option | Description |\n|--------|-------------|\n| `typed` | The signer types their signature. Their name is pre-filled. |\n| `drawn` | The signer draws their signature using a mouse, stylus, or touchscreen. |\n\nIf not specified, both `typed` and `drawn` are available, with `typed` as the default.\n", "type": "array", "uniqueItems": true, "items": { "type": "string", "enum": [ "typed", "drawn" ] }, "minItems": 1, "default": [ "typed", "drawn" ] }, "Recipient.SignatureScheme": { "x-schema-role": "enum", "x-schema-direction": "any", "title": "Signature Scheme", "description": "The legal scheme a qualified signature is produced under.\n\n| Scheme | Description |\n|--------|-------------|\n| `eu_eidas` | European Union qualified electronic signature under eIDAS. |\n\nAdditional schemes will be introduced in later releases.\n", "type": "string", "enum": [ "eu_eidas" ] }, "Recipient.SignerInput": { "x-schema-role": "model", "x-schema-direction": "input", "title": "Signer", "description": "A **signer** is a recipient who signs documents in the envelope. This is the most common recipient type. Every envelope must have at least one signer.\n\nDuring the ceremony, the signer reviews documents, fills in any assigned input fields, and adds their signature or initials at designated places. The signer must consent to use electronic signatures and finalize their actions to complete the ceremony.\n\nAll signer actions are recorded in the audit log attached to the final deliverable.\n\n### Delivery\n\nThe `delivery_type` controls whether SignatureAPI emails the completed deliverable to the signer. It defaults to `email`. Set it to `none` to distribute the deliverable yourself.\n\nThe signer receives an email with the ceremony link when the ceremony uses `email_link` authentication, which is the default.\n\n### Signature options\n\nThe `signature_options` array controls how the signer can sign. Options are `typed` (pre-filled with the signer's name) and `drawn` (mouse, stylus, or touchscreen). Both are enabled by default, with `typed` as the first option shown.\n", "type": "object", "additionalProperties": false, "properties": { "type": { "allOf": [ { "$ref": "#/$defs/Recipient.Type" }, { "const": "signer" } ] }, "key": { "$ref": "#/$defs/Recipient.Key" }, "email": { "$ref": "#/$defs/Recipient.Email" }, "name": { "$ref": "#/$defs/Recipient.Name" }, "ceremony": { "$ref": "#/$defs/Recipient.CeremonyInput" }, "delivery_type": { "allOf": [ { "$ref": "#/$defs/Recipient.DeliveryType" }, { "default": "email" } ] }, "signature_options": { "$ref": "#/$defs/Recipient.SignatureOptions" } }, "required": [ "type", "key", "email", "name" ] }, "Recipient.Type": { "x-schema-role": "property", "x-schema-direction": "any", "title": "Recipient Type", "description": "The type of the recipient. Determines what actions the recipient can perform during the ceremony.\n\n| Type | Description |\n|------|-------------|\n| `signer` | Signs documents. Every envelope must have at least one signing recipient. |\n| `qualified_signer` | Signs with a qualified electronic signature through a qualified trust service provider. |\n| `approver` | Reviews and approves documents without signing. |\n| `preparer` | Fills in document fields on behalf of another party. |\n| `automatic_signer` | The signature is applied automatically by the system. |\n", "type": "string", "enum": [ "signer", "qualified_signer", "approver", "preparer", "automatic_signer" ] } } }