{
  "openapi": "3.1.0",
  "info": {
    "title": "SignatureAPI: Recipients",
    "summary": "SignatureAPI is an API-first electronic signature platform.",
    "version": "1.18.0",
    "description": "SignatureAPI is a REST API for sending documents for electronic signature. It accepts JSON request bodies, returns JSON responses, and uses standard HTTP verbs and status codes.\n\n### Key concepts\n\nAn **envelope** is the central object. It holds documents and recipients, and manages the signing process from start to finish.\n\nA **document** is a PDF or DOCX file within an envelope. Documents contain **places** — interactive fields like signatures, initials, text inputs, checkboxes, and dropdowns positioned at specific locations.\n\nA **recipient** is a person who receives an envelope. There are three types:\n- **Signer** — signs documents\n- **Approver** — reviews and approves without signing\n- **Preparer** — fills in fields before the signer receives the documents\n\nA **ceremony** is the interactive session where a recipient authenticates and performs their actions. SignatureAPI supports three authentication methods: email link, email code, and custom.\n\nA **deliverable** is the final output — a signed PDF with an audit trail, generated after all recipients complete their actions.\n\nA **sender** is a verified email address that SignatureAPI sends signing requests on behalf of.\n\nAn **upload** is a file stored in SignatureAPI for use as a document source in envelopes.\n\n### HTTP Semantics\n\nWe use HTTP verbs GET, POST, DELETE as defined in RFC 9110, and PATCH as defined in RFC 5789.\n\nWe use the following HTTP Status codes for successful responses:\n\n- **200 OK**: Request succeeded for a GET, POST, or PATCH call.\n- **201 Created**: Request succeeded for a POST request that created a new resource. The response includes a Location header pointing to the newly created resource.\n\n### Versioning\n\nWe use [Semantic Versioning v2.0.0](https://semver.org/spec/v2.0.0.html):\n\n- We increment Major (the X in X.Y.Z) versions when we make a change that breaks backward compatibility. The current major version is 1.\n- We increment Minor (the Y in X.Y.Z) versions when we add backward compatible features.\n- We increment Patch (the Z in X.Y.Z) versions when we make backward compatible bug fixes or improvements in the documentation.\n\nSignatureAPI considers the following changes to break backward compatibility:\n\n- Removing or renaming fields, arguments, or enum values.\n- Removing endpoints.\n- Changing the type of fields in the response (for example, from string to integer).\n- Adding a new **required** request parameter.\n\nThese are not breaking changes:\n\n- Any additive change, such as adding endpoints, optional arguments, fields, or enum values.\n- Making a required request parameter optional.\n- Making a validation less restrictive.\n- Changes to error responses. _We do not recommend parsing error responses to perform business logic._\n- Changes to the order of fields returned in a response.\n- Changes to the length or format of opaque strings, such as object IDs, error messages, and other human-readable strings.\n- Adding new event types.\n- Changes in the structure and descriptions in this OpenAPI spec.",
    "contact": {
      "name": "Signature API, Inc.",
      "email": "support@signatureapi.com"
    },
    "termsOfService": "https://signatureapi.com/terms"
  },
  "servers": [
    {
      "description": "SignatureAPI Global Server.",
      "url": "https://api.signatureapi.com/v1"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "tags": [
    {
      "name": "Recipients",
      "description": "A **recipient** is a person who receives an envelope. Recipients can be signers, approvers, or preparers.\n"
    }
  ],
  "paths": {
    "/recipients/{recipientId}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/RecipientId"
        }
      ],
      "get": {
        "operationId": "GetRecipient",
        "summary": "Retrieve a recipient",
        "x-audience": "public",
        "tags": [
          "Recipients"
        ],
        "description": "Retrieves the details of a recipient, including their current status, ceremony information, and completion timestamp.\n\nUse this endpoint to check a recipient's progress through the signing workflow. The response includes the full recipient object with all properties for the recipient's type (signer, approver, or preparer).\n",
        "responses": {
          "200": {
            "description": "The recipient was retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Recipient.Recipient"
                }
              }
            }
          },
          "4XX": {
            "$ref": "#/components/responses/Shared.ClientError"
          },
          "5XX": {
            "$ref": "#/components/responses/Shared.ServerError"
          }
        }
      }
    },
    "/recipients/{recipientId}/replace": {
      "parameters": [
        {
          "$ref": "#/components/parameters/RecipientId"
        }
      ],
      "post": {
        "operationId": "ReplaceRecipient",
        "summary": "Replace a recipient",
        "x-audience": "public",
        "tags": [
          "Recipients"
        ],
        "description": "Replaces a recipient with a new person. The original recipient's status changes to `replaced`, and a new recipient is created with the provided name and email.\n\nUse this when a recipient can no longer complete the envelope — for example, after a hard bounce or if the wrong person was assigned.\n\nRecipients can be replaced as long as they have not completed yet and the envelope status is `processing` or `in_progress`. The new recipient inherits the original recipient's type, key, routing position, and assigned places.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email": {
                    "$ref": "#/components/schemas/Recipient.Email"
                  },
                  "name": {
                    "$ref": "#/components/schemas/Recipient.Name"
                  }
                },
                "required": [
                  "email",
                  "name"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The recipient was replaced successfully.",
            "headers": {
              "Location": {
                "$ref": "#/components/headers/Location"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Recipient.Recipient"
                }
              }
            }
          },
          "422": {
            "$ref": "#/components/responses/Shared.ValidationError"
          },
          "4XX": {
            "$ref": "#/components/responses/Shared.ClientError"
          },
          "5XX": {
            "$ref": "#/components/responses/Shared.ServerError"
          }
        }
      }
    },
    "/recipients/{recipientId}/resend": {
      "parameters": [
        {
          "$ref": "#/components/parameters/RecipientId"
        }
      ],
      "post": {
        "operationId": "ResendRequest",
        "summary": "Resend Request To Recipient",
        "x-audience": "public",
        "tags": [
          "Recipients"
        ],
        "description": "Resends the invitation email to a recipient who has not yet completed the envelope.\n\nThe request can be resent when the recipient status is `sent` or `soft_bounced` and the envelope status is `in_progress`.\n\nThe response includes a `can_resend_at` timestamp that indicates when the next resend is allowed. You must wait until after this time before resending again.\n\nYou can optionally customize the email subject and message for this specific resend. If not provided, the original subject and message are used.\n",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Recipient.ResendInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The request was resent to the recipient.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Recipient.ResendResponse"
                }
              }
            }
          },
          "422": {
            "$ref": "#/components/responses/Shared.ValidationError"
          },
          "4XX": {
            "$ref": "#/components/responses/Shared.ClientError"
          },
          "5XX": {
            "$ref": "#/components/responses/Shared.ServerError"
          }
        }
      }
    },
    "/recipients/{recipientId}/ceremonies": {
      "parameters": [
        {
          "$ref": "#/components/parameters/RecipientId"
        }
      ],
      "post": {
        "operationId": "CreateRecipientCeremony",
        "summary": "Create ceremony for recipient",
        "x-audience": "public",
        "tags": [
          "Recipients"
        ],
        "description": "Creates a new ceremony for the recipient. Any previous active ceremony for this recipient is automatically revoked.\n\nUse this endpoint to create a ceremony after the envelope has been created, or to replace an existing ceremony with different authentication settings.\n\nThe response includes the ceremony configuration and, when applicable, the ceremony URL. The **first** authentication method decides this: the `url` property is populated when the first method is `email_code` or `custom`. When the first method is `email_link`, SignatureAPI delivers the URL by email and the `url` property is `null` — including when another method such as `email_code` follows it.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Ceremony.CeremonyInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The ceremony was created successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Ceremony.Ceremony"
                }
              }
            }
          },
          "422": {
            "$ref": "#/components/responses/Shared.ValidationError"
          },
          "4XX": {
            "$ref": "#/components/responses/Shared.ClientError"
          },
          "5XX": {
            "$ref": "#/components/responses/Shared.ServerError"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "Authentication to the API is performed via an API key in the `X-API-Key` header.\n\nYour API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.\n"
      }
    },
    "schemas": {
      "Envelope.Id": {
        "x-schema-role": "property",
        "x-schema-direction": "output",
        "type": "string",
        "format": "uuid",
        "title": "Envelope Id",
        "description": "The unique identifier of the envelope, in UUID format.",
        "examples": [
          "5e5ace5e-bd1e-4d5a-bb1f-6a2b2e42cd13"
        ]
      },
      "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,
        "examples": [
          "explorer"
        ]
      },
      "Recipient.Id": {
        "x-schema-role": "property",
        "x-schema-direction": "output",
        "title": "Recipient Id",
        "description": "The unique identifier of the recipient. Recipient IDs use the `re_` prefix.\n",
        "type": "string",
        "examples": [
          "re_MDGrLQX02X6eHBCL84mHI72"
        ]
      },
      "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"
        ],
        "examples": [
          "signer"
        ]
      },
      "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,
        "examples": [
          "jeff@example.com"
        ]
      },
      "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,
        "examples": [
          "Jeff Spender"
        ]
      },
      "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\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.",
        "enum": [
          "email_link",
          "email_code",
          "custom"
        ]
      },
      "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,
        "examples": [
          "Please sign the Mars Exploration Agreement"
        ]
      },
      "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,
        "examples": [
          "Thank you for accepting to be a Mars explorer! Please sign this agreement.",
          ""
        ]
      },
      "Ceremony.EmailLinkAuthentication": {
        "x-schema-role": "model",
        "x-schema-direction": "output",
        "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",
        "properties": {
          "type": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Ceremony.AuthenticationType"
              },
              {
                "const": "email_link"
              }
            ]
          },
          "subject_override": {
            "$ref": "#/components/schemas/Ceremony.EmailLinkSubjectOverride"
          },
          "message_override": {
            "$ref": "#/components/schemas/Ceremony.EmailLinkMessageOverride"
          }
        },
        "required": [
          "type",
          "subject_override",
          "message_override"
        ]
      },
      "Ceremony.EmailCodeAuthentication": {
        "x-schema-role": "model",
        "x-schema-direction": "output",
        "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",
        "properties": {
          "type": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Ceremony.AuthenticationType"
              },
              {
                "const": "email_code"
              }
            ]
          }
        },
        "required": [
          "type"
        ]
      },
      "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",
        "example": "ACME Inc."
      },
      "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,
        "example": {
          "Authenticated At": "21:10:15 UTC December 31, 2025",
          "Session ID": "99926348946197326"
        }
      },
      "Ceremony.CustomAuthentication": {
        "x-schema-role": "model",
        "x-schema-direction": "output",
        "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",
        "properties": {
          "type": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Ceremony.AuthenticationType"
              },
              {
                "const": "custom"
              }
            ]
          },
          "provider": {
            "$ref": "#/components/schemas/Ceremony.CustomAuthenticationProvider"
          },
          "data": {
            "$ref": "#/components/schemas/Ceremony.CustomAuthenticationData"
          }
        },
        "required": [
          "type",
          "provider",
          "data"
        ]
      },
      "Ceremony.Authentication": {
        "x-schema-role": "property",
        "x-schema-direction": "output",
        "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\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.",
        "type": "array",
        "minItems": 1,
        "maxItems": 5,
        "items": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/Ceremony.EmailLinkAuthentication"
            },
            {
              "$ref": "#/components/schemas/Ceremony.EmailCodeAuthentication"
            },
            {
              "$ref": "#/components/schemas/Ceremony.CustomAuthentication"
            }
          ]
        },
        "discriminator": {
          "propertyName": "type",
          "mapping": {
            "email_link": "#/components/schemas/Ceremony.EmailLinkAuthentication",
            "email_code": "#/components/schemas/Ceremony.EmailCodeAuthentication",
            "custom": "#/components/schemas/Ceremony.CustomAuthentication"
          }
        }
      },
      "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",
        "example": [
          "https://app.example.com"
        ],
        "maxItems": 10,
        "items": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100
        },
        "default": []
      },
      "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",
        "example": "https://www.example.com/signing-complete",
        "default": null
      },
      "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",
        "example": 3,
        "default": 3
      },
      "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",
        "example": "standard",
        "enum": [
          "standard",
          "short"
        ],
        "default": "standard"
      },
      "Ceremony.Url": {
        "x-schema-role": "property",
        "x-schema-direction": "output",
        "type": [
          "string",
          "null"
        ],
        "title": "Ceremony URL",
        "format": "uri",
        "description": "The URL where the recipient can access the ceremony. You can embed this link in your application or share it with the recipient directly.\n\nThis property is `null` when:\n- The ceremony's **first** authentication method is `email_link`, because SignatureAPI delivers the URL by email. This applies whether or not other methods follow it.\n- The ceremony is not active (for example, it has been completed, revoked, or declined).\n\nThe URL expires after 30 days by default, or when a new ceremony is created for the same recipient.\n",
        "example": "https://sign.signatureapi.com/cc/cer_1234567890"
      },
      "Ceremony.Ceremony": {
        "x-schema-role": "model",
        "x-schema-direction": "output",
        "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",
        "properties": {
          "authentication": {
            "$ref": "#/components/schemas/Ceremony.Authentication"
          },
          "embeddable_in": {
            "$ref": "#/components/schemas/Ceremony.EmbeddableIn"
          },
          "redirect_url": {
            "$ref": "#/components/schemas/Ceremony.RedirectUrl"
          },
          "redirect_delay": {
            "$ref": "#/components/schemas/Ceremony.RedirectDelay"
          },
          "url_variant": {
            "$ref": "#/components/schemas/Ceremony.UrlVariant"
          },
          "url": {
            "$ref": "#/components/schemas/Ceremony.Url"
          }
        },
        "required": [
          "authentication",
          "embeddable_in",
          "redirect_url",
          "redirect_delay",
          "url_variant",
          "url"
        ]
      },
      "Recipient.Ceremony": {
        "x-schema-role": "property",
        "x-schema-direction": "output",
        "title": "Ceremony",
        "description": "The current ceremony for the recipient. Contains authentication settings, redirect configuration, and the ceremony URL.\n\nReturns `null` if no ceremony has been created yet.\n",
        "anyOf": [
          {
            "$ref": "#/components/schemas/Ceremony.Ceremony"
          },
          {
            "type": "null",
            "title": "No Ceremony",
            "description": "No ceremony has been created for the recipient."
          }
        ]
      },
      "Recipient.CeremonyCreation": {
        "x-schema-role": "property",
        "x-schema-direction": "any",
        "title": "Ceremony Creation",
        "type": "string",
        "description": "How ceremonies are created for this recipient.\n\n**Deprecated**: Use the `ceremony` property on the recipient instead.\n",
        "enum": [
          "automatic",
          "manual"
        ],
        "examples": [
          "automatic"
        ],
        "default": "automatic",
        "deprecated": true
      },
      "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",
        "examples": [
          "email"
        ]
      },
      "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.Status": {
        "x-schema-role": "property",
        "x-schema-direction": "output",
        "title": "Recipient Status",
        "type": "string",
        "description": "The current status of a recipient in the signing workflow.\n\n| Status | Description |\n|--------|-------------|\n| `pending` | The envelope has not been sent to the recipient yet. This is the initial status. |\n| `awaiting` | The recipient is waiting for previous recipients in the routing order to complete. |\n| `sent` | The invitation email has been sent to the recipient. |\n| `completed` | The recipient has completed their required actions (e.g., signed, approved). |\n| `rejected` | The recipient declined to complete the envelope. |\n| `soft_bounced` | The email was temporarily undeliverable (e.g., full mailbox). You can resend the request. |\n| `hard_bounced` | The email was permanently undeliverable (e.g., invalid address). Use the Replace endpoint to assign a new recipient. |\n| `failed` | An error occurred and the email could not be sent. |\n| `replaced` | The recipient was replaced with a new one via the Replace endpoint. |\n",
        "enum": [
          "pending",
          "awaiting",
          "sent",
          "completed",
          "rejected",
          "soft_bounced",
          "hard_bounced",
          "failed",
          "replaced"
        ],
        "examples": [
          "completed"
        ]
      },
      "Recipient.StatusUpdatedAt": {
        "x-schema-role": "property",
        "x-schema-direction": "output",
        "type": "string",
        "format": "date-time",
        "title": "Recipient Status Updated At",
        "description": "The time at which the recipient's status last changed. Updates whenever the recipient transitions to a new status.\n"
      },
      "Recipient.CompletedAt": {
        "x-schema-role": "property",
        "x-schema-direction": "output",
        "type": [
          "string",
          "null"
        ],
        "format": "date-time",
        "title": "Recipient Completed At",
        "description": "The time at which the recipient completed their required actions on the envelope, such as signing or approving. Returns `null` if the recipient has not completed yet.\n"
      },
      "Recipient.Signer": {
        "x-schema-role": "model",
        "x-schema-direction": "output",
        "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",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/Recipient.Id"
          },
          "envelope_id": {
            "$ref": "#/components/schemas/Envelope.Id"
          },
          "type": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Recipient.Type"
              },
              {
                "const": "signer"
              }
            ]
          },
          "key": {
            "$ref": "#/components/schemas/Recipient.Key"
          },
          "email": {
            "$ref": "#/components/schemas/Recipient.Email"
          },
          "name": {
            "$ref": "#/components/schemas/Recipient.Name"
          },
          "ceremony": {
            "$ref": "#/components/schemas/Recipient.Ceremony"
          },
          "ceremony_creation": {
            "$ref": "#/components/schemas/Recipient.CeremonyCreation"
          },
          "delivery_type": {
            "$ref": "#/components/schemas/Recipient.DeliveryType"
          },
          "signature_options": {
            "$ref": "#/components/schemas/Recipient.SignatureOptions"
          },
          "status": {
            "$ref": "#/components/schemas/Recipient.Status"
          },
          "status_updated_at": {
            "$ref": "#/components/schemas/Recipient.StatusUpdatedAt"
          },
          "completed_at": {
            "$ref": "#/components/schemas/Recipient.CompletedAt"
          }
        },
        "required": [
          "id",
          "envelope_id",
          "type",
          "key",
          "email",
          "name",
          "ceremony",
          "ceremony_creation",
          "delivery_type",
          "signature_options",
          "status",
          "status_updated_at",
          "completed_at"
        ]
      },
      "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.SignatureCertificate": {
        "x-schema-role": "model",
        "x-schema-direction": "output",
        "title": "Signature Certificate",
        "description": "Details of the signing certificate issued to the recipient for a qualified signature.\nPresent once the signature has been produced.\n",
        "type": "object",
        "properties": {
          "subject": {
            "type": "string",
            "description": "The distinguished name of the certificate subject.",
            "example": "CN=Jane Doe, C=DE"
          },
          "issuer": {
            "type": "string",
            "description": "The distinguished name of the certificate issuer.",
            "example": "CN=Example QTSP Qualified CA, C=DE"
          },
          "serial": {
            "type": "string",
            "description": "The certificate serial number.",
            "example": "5f2c1a9be4d07b3a"
          },
          "valid_from": {
            "type": "string",
            "format": "date-time",
            "description": "The date and time the certificate became valid.",
            "example": "2026-08-05T10:15:00Z"
          },
          "valid_to": {
            "type": "string",
            "format": "date-time",
            "description": "The date and time the certificate expires.",
            "example": "2027-08-05T10:15:00Z"
          }
        },
        "required": [
          "subject",
          "issuer",
          "serial",
          "valid_from",
          "valid_to"
        ]
      },
      "Recipient.QualifiedSigner": {
        "x-schema-role": "model",
        "x-schema-direction": "output",
        "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",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/Recipient.Id"
          },
          "envelope_id": {
            "$ref": "#/components/schemas/Envelope.Id"
          },
          "type": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Recipient.Type"
              },
              {
                "const": "qualified_signer"
              }
            ]
          },
          "key": {
            "$ref": "#/components/schemas/Recipient.Key"
          },
          "email": {
            "$ref": "#/components/schemas/Recipient.Email"
          },
          "name": {
            "$ref": "#/components/schemas/Recipient.Name"
          },
          "ceremony": {
            "$ref": "#/components/schemas/Recipient.Ceremony"
          },
          "ceremony_creation": {
            "$ref": "#/components/schemas/Recipient.CeremonyCreation"
          },
          "delivery_type": {
            "$ref": "#/components/schemas/Recipient.DeliveryType"
          },
          "signature_options": {
            "$ref": "#/components/schemas/Recipient.SignatureOptions"
          },
          "scheme": {
            "$ref": "#/components/schemas/Recipient.SignatureScheme"
          },
          "certificate": {
            "$ref": "#/components/schemas/Recipient.SignatureCertificate"
          },
          "status": {
            "$ref": "#/components/schemas/Recipient.Status"
          },
          "status_updated_at": {
            "$ref": "#/components/schemas/Recipient.StatusUpdatedAt"
          },
          "completed_at": {
            "$ref": "#/components/schemas/Recipient.CompletedAt"
          }
        },
        "required": [
          "id",
          "envelope_id",
          "type",
          "key",
          "email",
          "name",
          "ceremony",
          "ceremony_creation",
          "delivery_type",
          "signature_options",
          "scheme",
          "status",
          "status_updated_at",
          "completed_at"
        ]
      },
      "Recipient.Approver": {
        "x-schema-role": "model",
        "x-schema-direction": "output",
        "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",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/Recipient.Id"
          },
          "envelope_id": {
            "$ref": "#/components/schemas/Envelope.Id"
          },
          "type": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Recipient.Type"
              },
              {
                "const": "approver"
              }
            ]
          },
          "key": {
            "$ref": "#/components/schemas/Recipient.Key"
          },
          "email": {
            "$ref": "#/components/schemas/Recipient.Email"
          },
          "name": {
            "$ref": "#/components/schemas/Recipient.Name"
          },
          "ceremony": {
            "$ref": "#/components/schemas/Recipient.Ceremony"
          },
          "ceremony_creation": {
            "$ref": "#/components/schemas/Recipient.CeremonyCreation"
          },
          "delivery_type": {
            "$ref": "#/components/schemas/Recipient.DeliveryType"
          },
          "status": {
            "$ref": "#/components/schemas/Recipient.Status"
          },
          "status_updated_at": {
            "$ref": "#/components/schemas/Recipient.StatusUpdatedAt"
          },
          "completed_at": {
            "$ref": "#/components/schemas/Recipient.CompletedAt"
          }
        },
        "required": [
          "id",
          "envelope_id",
          "type",
          "key",
          "email",
          "name",
          "ceremony",
          "ceremony_creation",
          "delivery_type",
          "status",
          "status_updated_at",
          "completed_at"
        ]
      },
      "Recipient.Preparer": {
        "x-schema-role": "model",
        "x-schema-direction": "output",
        "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",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/Recipient.Id"
          },
          "envelope_id": {
            "$ref": "#/components/schemas/Envelope.Id"
          },
          "type": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Recipient.Type"
              },
              {
                "const": "preparer"
              }
            ]
          },
          "key": {
            "$ref": "#/components/schemas/Recipient.Key"
          },
          "email": {
            "$ref": "#/components/schemas/Recipient.Email"
          },
          "name": {
            "$ref": "#/components/schemas/Recipient.Name"
          },
          "ceremony": {
            "$ref": "#/components/schemas/Recipient.Ceremony"
          },
          "ceremony_creation": {
            "$ref": "#/components/schemas/Recipient.CeremonyCreation"
          },
          "delivery_type": {
            "$ref": "#/components/schemas/Recipient.DeliveryType"
          },
          "status": {
            "$ref": "#/components/schemas/Recipient.Status"
          },
          "status_updated_at": {
            "$ref": "#/components/schemas/Recipient.StatusUpdatedAt"
          },
          "completed_at": {
            "$ref": "#/components/schemas/Recipient.CompletedAt"
          }
        },
        "required": [
          "id",
          "envelope_id",
          "type",
          "key",
          "email",
          "name",
          "ceremony",
          "ceremony_creation",
          "delivery_type",
          "status",
          "status_updated_at",
          "completed_at"
        ]
      },
      "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.PresetSymbolDrawn": {
        "x-schema-role": "model",
        "x-schema-direction": "output",
        "title": "Drawn Preset Symbol",
        "description": "A drawn symbol to be used as a signature or initials.",
        "type": "object",
        "properties": {
          "type": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Recipient.PresetSymbolType"
              },
              {
                "const": "drawn"
              }
            ]
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "The URL of an upload of a PNG image.\n",
            "example": "https://api.signatureapi.com/v1/uploads/upl_1sAAaVfabdt0esVjmSTmLA"
          }
        },
        "required": [
          "type",
          "url"
        ]
      },
      "Recipient.PresetSymbol": {
        "x-schema-role": "model",
        "x-schema-direction": "output",
        "title": "Preset Symbol",
        "description": "A symbol (signature or initials) supplied up-front for an automatic signer.\n",
        "oneOf": [
          {
            "$ref": "#/components/schemas/Recipient.PresetSymbolDrawn"
          }
        ],
        "discriminator": {
          "propertyName": "type",
          "mapping": {
            "drawn": "#/components/schemas/Recipient.PresetSymbolDrawn"
          }
        }
      },
      "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,
        "examples": [
          "With permission given and recorded on Jan 1 2026"
        ]
      },
      "Recipient.AutomaticSigner": {
        "x-schema-role": "model",
        "x-schema-direction": "output",
        "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",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/Recipient.Id"
          },
          "envelope_id": {
            "$ref": "#/components/schemas/Envelope.Id"
          },
          "type": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Recipient.Type"
              },
              {
                "const": "automatic_signer"
              }
            ]
          },
          "key": {
            "$ref": "#/components/schemas/Recipient.Key"
          },
          "name": {
            "$ref": "#/components/schemas/Recipient.Name"
          },
          "signature": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/Recipient.PresetSymbol"
              },
              {
                "type": "null",
                "title": "No Preset Signature",
                "description": "No preset signature was supplied for this automatic signer."
              }
            ]
          },
          "initials": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/Recipient.PresetSymbol"
              },
              {
                "type": "null",
                "title": "No Preset Initials",
                "description": "No preset initials were supplied for this automatic signer."
              }
            ]
          },
          "mandate": {
            "$ref": "#/components/schemas/Recipient.Mandate"
          },
          "status": {
            "$ref": "#/components/schemas/Recipient.Status"
          },
          "status_updated_at": {
            "$ref": "#/components/schemas/Recipient.StatusUpdatedAt"
          },
          "completed_at": {
            "$ref": "#/components/schemas/Recipient.CompletedAt"
          }
        },
        "required": [
          "id",
          "envelope_id",
          "type",
          "key",
          "name",
          "signature",
          "initials",
          "mandate",
          "status",
          "status_updated_at",
          "completed_at"
        ]
      },
      "Recipient.Recipient": {
        "x-schema-role": "model",
        "x-schema-direction": "output",
        "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": "#/components/schemas/Recipient.Signer"
          },
          {
            "$ref": "#/components/schemas/Recipient.QualifiedSigner"
          },
          {
            "$ref": "#/components/schemas/Recipient.Approver"
          },
          {
            "$ref": "#/components/schemas/Recipient.Preparer"
          },
          {
            "$ref": "#/components/schemas/Recipient.AutomaticSigner"
          }
        ],
        "discriminator": {
          "propertyName": "type",
          "mapping": {
            "signer": "#/components/schemas/Recipient.Signer",
            "qualified_signer": "#/components/schemas/Recipient.QualifiedSigner",
            "approver": "#/components/schemas/Recipient.Approver",
            "preparer": "#/components/schemas/Recipient.Preparer",
            "automatic_signer": "#/components/schemas/Recipient.AutomaticSigner"
          }
        }
      },
      "Shared.Problem": {
        "x-schema-role": "property",
        "x-schema-direction": "output",
        "type": "object",
        "description": "An error response following the RFC 9457 Problem Details format. The API returns this object with a `application/problem+json` content type when a request fails. Use the `type` URL to identify the error programmatically and the `detail` field to understand what went wrong.\n",
        "additionalProperties": false,
        "properties": {
          "type": {
            "type": "string",
            "description": "A URL that identifies the problem type. Points to documentation explaining the error.",
            "format": "uri",
            "example": "https://signatureapi.com/docs/v1/errors/invalid-api-key"
          },
          "title": {
            "type": "string",
            "description": "A short, human-readable summary of the problem type.",
            "example": "Invalid API Key"
          },
          "status": {
            "type": "integer",
            "description": "The HTTP status code for this error. Matches the status code in the HTTP response.",
            "minimum": 100,
            "maximum": 599,
            "example": 401
          },
          "detail": {
            "type": "string",
            "description": "A human-readable explanation specific to this occurrence of the problem.",
            "example": "Please provide a valid API key in the X-API-Key header."
          }
        },
        "required": [
          "type",
          "title",
          "status",
          "detail"
        ]
      },
      "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": "#/components/schemas/Ceremony.AuthenticationType"
              },
              {
                "const": "email_link"
              }
            ]
          },
          "subject_override": {
            "$ref": "#/components/schemas/Ceremony.EmailLinkSubjectOverride"
          },
          "message_override": {
            "$ref": "#/components/schemas/Ceremony.EmailLinkMessageOverride"
          }
        },
        "required": [
          "type"
        ]
      },
      "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": "#/components/schemas/Ceremony.AuthenticationType"
              },
              {
                "const": "email_code"
              }
            ]
          }
        },
        "required": [
          "type"
        ]
      },
      "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": "#/components/schemas/Ceremony.AuthenticationType"
              },
              {
                "const": "custom"
              }
            ]
          },
          "provider": {
            "$ref": "#/components/schemas/Ceremony.CustomAuthenticationProvider"
          },
          "data": {
            "$ref": "#/components/schemas/Ceremony.CustomAuthenticationData"
          }
        },
        "required": [
          "type",
          "provider",
          "data"
        ]
      },
      "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\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.",
        "type": "array",
        "minItems": 1,
        "maxItems": 5,
        "items": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/Ceremony.EmailLinkAuthenticationInput"
            },
            {
              "$ref": "#/components/schemas/Ceremony.EmailCodeAuthenticationInput"
            },
            {
              "$ref": "#/components/schemas/Ceremony.CustomAuthenticationInput"
            }
          ]
        },
        "discriminator": {
          "propertyName": "type",
          "mapping": {
            "email_link": "#/components/schemas/Ceremony.EmailLinkAuthenticationInput",
            "email_code": "#/components/schemas/Ceremony.EmailCodeAuthenticationInput",
            "custom": "#/components/schemas/Ceremony.CustomAuthenticationInput"
          }
        }
      },
      "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": "#/components/schemas/Ceremony.AuthenticationInput"
          },
          "embeddable_in": {
            "$ref": "#/components/schemas/Ceremony.EmbeddableIn"
          },
          "redirect_url": {
            "$ref": "#/components/schemas/Ceremony.RedirectUrl"
          },
          "redirect_delay": {
            "$ref": "#/components/schemas/Ceremony.RedirectDelay"
          },
          "url_variant": {
            "$ref": "#/components/schemas/Ceremony.UrlVariant"
          }
        },
        "required": [
          "authentication"
        ]
      },
      "Shared.ValidationProblem": {
        "x-schema-role": "property",
        "x-schema-direction": "output",
        "description": "A validation error response following the RFC 9457 Problem Details format. The API returns this object with HTTP status 422 when a request body fails validation. The `errors` array lists each field-level problem so you can fix them all in one pass.\n",
        "properties": {
          "type": {
            "type": "string",
            "description": "A URL pointing to the validation error documentation. Always `https://signatureapi.com/docs/v1/errors/validation-error`.",
            "format": "uri",
            "const": "https://signatureapi.com/docs/v1/errors/validation-error",
            "example": "https://signatureapi.com/docs/v1/errors/validation-error"
          },
          "title": {
            "type": "string",
            "description": "A short summary of the problem type. Always `Validation Error`.",
            "const": "Validation Error",
            "example": "Validation Error"
          },
          "status": {
            "type": "integer",
            "description": "The HTTP status code. Always `422` for validation errors.",
            "const": 422,
            "example": 422
          },
          "errors": {
            "type": "array",
            "description": "A list of human-readable messages describing each validation failure.",
            "items": {
              "type": "string"
            },
            "example": [
              "documents[0].url protocol must be HTTPS",
              "recipients[0].email must be a valid email address"
            ]
          }
        },
        "required": [
          "type",
          "title",
          "status",
          "errors"
        ]
      },
      "Recipient.ResendSubjectOverride": {
        "x-schema-role": "property",
        "x-schema-direction": "any",
        "type": [
          "string",
          "null"
        ],
        "title": "Resend Email Subject Override",
        "description": "Custom email subject for the resend invitation email. Overrides the default subject for this resend only.\n\nIf not provided or `null`, the envelope title is used as the email subject.\n",
        "minLength": 1,
        "maxLength": 500,
        "examples": [
          "Reminder: Please sign the Mars Exploration Agreement"
        ]
      },
      "Recipient.ResendMessageOverride": {
        "x-schema-role": "property",
        "x-schema-direction": "any",
        "type": [
          "string",
          "null"
        ],
        "title": "Resend Email Message Override",
        "description": "Custom message body for the resend invitation email. Overrides the default message for this resend only.\n\nIf not provided or `null`, the envelope message is used. Set to an empty string `\"\"` to send no message in the email.\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\n",
        "maxLength": 2000,
        "examples": [
          "This is a friendly reminder to sign the agreement. Please complete it at your earliest convenience.",
          ""
        ]
      },
      "Recipient.ResendInput": {
        "x-schema-role": "schema",
        "x-schema-direction": "input",
        "title": "Resend Recipient Input",
        "description": "Input for resending the invitation email to a recipient. All fields are optional. If omitted, the original email subject and message are used.\n",
        "type": "object",
        "properties": {
          "subject_override": {
            "$ref": "#/components/schemas/Recipient.ResendSubjectOverride"
          },
          "message_override": {
            "$ref": "#/components/schemas/Recipient.ResendMessageOverride"
          }
        }
      },
      "Recipient.CanResendAt": {
        "x-schema-role": "property",
        "x-schema-direction": "output",
        "type": "string",
        "format": "date-time",
        "title": "Can Resend At",
        "description": "The earliest time at which you can resend the invitation to this recipient. This enforces a cooldown period between resend attempts.\n\nWait until after this timestamp before calling the Resend Request endpoint again.\n",
        "examples": [
          "2025-12-31T22:00:00.000Z"
        ]
      },
      "Recipient.ResendResponse": {
        "x-schema-role": "schema",
        "x-schema-direction": "output",
        "title": "Resend Recipient Response",
        "description": "Response after resending the invitation email to a recipient.\n\nIncludes `can_resend_at`, which indicates the earliest time you can send the next resend for this recipient.\n\nThe `subject_override` and `message_override` fields return what was passed in the resend request. If not provided in the request, they are `null`. The actual email uses resolved values, falling back to ceremony overrides or envelope defaults.\n",
        "type": "object",
        "properties": {
          "can_resend_at": {
            "$ref": "#/components/schemas/Recipient.CanResendAt"
          },
          "subject_override": {
            "$ref": "#/components/schemas/Recipient.ResendSubjectOverride"
          },
          "message_override": {
            "$ref": "#/components/schemas/Recipient.ResendMessageOverride"
          }
        },
        "required": [
          "can_resend_at",
          "subject_override",
          "message_override"
        ]
      }
    },
    "parameters": {
      "RecipientId": {
        "name": "recipientId",
        "in": "path",
        "description": "The unique identifier of a recipient.",
        "required": true,
        "schema": {
          "$ref": "#/components/schemas/Recipient.Id"
        }
      }
    },
    "responses": {
      "Shared.ClientError": {
        "description": "The request cannot be processed due to an issue on the client's side. This may include invalid request format, insufficient permissions, or requesting non-existent resources. The client should review and correct the request.\n\nThis error covers HTTP status codes in the 400 to 499 range. The most common are:\n\n- 400 Bad Request (`bad-request`: the request body is not valid JSON)\n- 401 Unauthorized\n- 402 Payment Required (`live-mode-paused`: live API access is paused because an invoice is unpaid; test keys keep working)\n- 403 Forbidden\n- 409 Conflict\n- 410 Gone\n- 404 Not Found\n- 413 Request Too Large (`request-too-large`: a JSON request body exceeds 1500 KiB, a form-encoded body exceeds 100 KiB, or a form-encoded body has too many parameters)\n- 415 Unsupported Media Type (`unsupported-media-type`: the request body's charset or content encoding is not supported)\n- 422 Unprocessable Content.\n",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Shared.Problem"
            },
            "example": {
              "type": "https://signatureapi.com/docs/v1/errors/api-key-required",
              "title": "The API Key is required",
              "status": 401,
              "detail": "A valid API key is required in the X-API-Key header of all requests."
            }
          }
        }
      },
      "Shared.ServerError": {
        "description": "The request cannot be processed due to an issue on the server's side. The client can retry the request in a few minutes, or contact support if the error persists.\n",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Shared.Problem"
            },
            "example": {
              "type": "https://signatureapi.com/docs/v1/errors/server-error",
              "title": "Internal Server Error",
              "status": 500,
              "detail": "There was a problem in our server and your request was not fulfilled. Try again later. If the error persists, please contact support.\n"
            }
          }
        }
      },
      "Shared.ValidationError": {
        "description": "The request cannot be processed due to validation errors. This typically involves issues like missing required fields, invalid data formats, or value constraints not being met.\n",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Shared.ValidationProblem"
            },
            "example": {
              "type": "https://signatureapi.com/docs/v1/errors/validation-error",
              "title": "Validation Error",
              "status": 422,
              "errors": [
                "The title is required",
                "The sender.email is not a valid email address",
                "The value of recipients[0].key is too long"
              ]
            }
          }
        }
      }
    },
    "headers": {
      "Location": {
        "required": true,
        "description": "The URL of the created resource",
        "schema": {
          "type": "string",
          "format": "uri"
        }
      }
    }
  }
}
