openapi: 3.1.0
info:
  title: SignatureAPI
  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.

    ### Key concepts

    An **envelope** is the central object. It holds documents and recipients, and manages the signing process from start to finish.

    A **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.

    A **recipient** is a person who receives an envelope. There are three types:
    - **Signer** — signs documents
    - **Approver** — reviews and approves without signing
    - **Preparer** — fills in fields before the signer receives the documents

    A **ceremony** is the interactive session where a recipient authenticates and performs their actions. SignatureAPI supports three authentication methods: email link, email code, and custom.

    A **deliverable** is the final output — a signed PDF with an audit trail, generated after all recipients complete their actions.

    A **sender** is a verified email address that SignatureAPI sends signing requests on behalf of.

    An **upload** is a file stored in SignatureAPI for use as a document source in envelopes.

    ### HTTP Semantics

    We use HTTP verbs GET, POST, DELETE as defined in RFC 9110, and PATCH as defined in RFC 5789.

    We use the following HTTP Status codes for successful responses:

    - **200 OK**: Request succeeded for a GET, POST, or PATCH call.
    - **201 Created**: Request succeeded for a POST request that created a new resource. The response includes a Location header pointing to the newly created resource.

    ### Versioning

    We use [Semantic Versioning v2.0.0](https://semver.org/spec/v2.0.0.html):

    - 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.
    - We increment Minor (the Y in X.Y.Z) versions when we add backward compatible features.
    - We increment Patch (the Z in X.Y.Z) versions when we make backward compatible bug fixes or improvements in the documentation.

    SignatureAPI considers the following changes to break backward compatibility:

    - Removing or renaming fields, arguments, or enum values.
    - Removing endpoints.
    - Changing the type of fields in the response (for example, from string to integer).
    - Adding a new **required** request parameter.

    These are not breaking changes:

    - Any additive change, such as adding endpoints, optional arguments, fields, or enum values.
    - Making a required request parameter optional.
    - Making a validation less restrictive.
    - Changes to error responses. _We do not recommend parsing error responses to perform business logic._
    - Changes to the order of fields returned in a response.
    - Changes to the length or format of opaque strings, such as object IDs, error messages, and other human-readable strings.
    - Adding new event types.
    - 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: Envelopes
    description: |
      An **envelope** holds documents and recipients, and manages the signing process from start to finish. Create an envelope to send documents for signature.
  - name: Recipients
    description: |
      A **recipient** is a person who receives an envelope. Recipients can be signers, approvers, or preparers.
  - name: Documents
    description: |
      A **document** is a PDF or DOCX file within an envelope. Documents contain places — interactive fields like signatures, text inputs, and checkboxes.
  - name: Deliverables
    description: |
      A **deliverable** is the final signed PDF generated after an envelope completes. It contains the signed documents and an audit trail.
  - name: Events
    description: |
      An **event** records a change or action in your account. Events are delivered via webhooks and available through the API.
  - name: Uploads
    description: |
      An **upload** is a file stored in SignatureAPI for use as a document source in envelopes. Supports PDF, DOCX, and image files.
paths:
  /envelopes:
    post:
      operationId: CreateEnvelope
      summary: Create an envelope
      x-audience: public
      tags:
        - Envelopes
      description: |
        Creates a new envelope and starts the signing process. The envelope begins in `processing` status while documents are validated and prepared, then transitions to `in_progress` once recipients are notified.

        At minimum, you must provide a `title`, at least one `document`, and at least one `recipient`. All other fields are optional and have sensible defaults.

        Documents must be publicly accessible PDF or DOCX files. Each document can include interactive elements (places) such as signature fields, text inputs, and checkboxes.

        By default, recipients receive the envelope sequentially in the order listed. Set `routing` to `parallel` to send to all recipients at the same time.

        A `standard` deliverable (signed documents plus audit log) is generated automatically upon completion. You can customize the deliverable type, password-protect it, or select which documents to include.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Envelope.EnvelopeInput'
      responses:
        '201':
          description: The envelope was created successfully.
          headers:
            Location:
              $ref: '#/components/headers/Location'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope.Envelope'
        '422':
          $ref: '#/components/responses/Shared.ValidationError'
        4XX:
          $ref: '#/components/responses/Shared.ClientError'
        5XX:
          $ref: '#/components/responses/Shared.ServerError'
    get:
      operationId: ListEnvelopes
      summary: List envelopes
      x-audience: public
      tags:
        - Envelopes
      description: |
        Returns a paginated list of envelopes in the current account, sorted by creation date with the most recent envelopes first.

        Use the `status` parameter to filter by envelope status (e.g., `completed`, `in_progress`). Use the `topic` parameter to filter by a specific topic tag.

        Results are paginated with a default and maximum limit of 20 envelopes per page. Use the `links.next` and `links.previous` URLs in the response to navigate between pages.
      parameters:
        - $ref: '#/components/parameters/EnvelopeStatus'
        - $ref: '#/components/parameters/EnvelopeTopic'
        - $ref: '#/components/parameters/PaginationLimit'
      responses:
        '200':
          description: The list of envelopes was retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  links:
                    $ref: '#/components/schemas/Shared.PaginationLinks'
                  data:
                    type: array
                    description: An array of envelopes.
                    items:
                      $ref: '#/components/schemas/Envelope.Envelope'
        4XX:
          $ref: '#/components/responses/Shared.ClientError'
        5XX:
          $ref: '#/components/responses/Shared.ServerError'
  /envelopes/{envelopeId}:
    parameters:
      - $ref: '#/components/parameters/EnvelopeId'
    get:
      operationId: GetEnvelope
      summary: Retrieve an envelope
      x-audience: public
      tags:
        - Envelopes
      description: |
        Retrieves the full details of an envelope, including its documents, recipients, deliverable, sender information, and captures.

        Use this endpoint to check the current status of an envelope, retrieve recipient ceremony URLs, or access the deliverable download URL after completion.

        The response includes all envelope properties regardless of the envelope's current status. Fields that are not yet available (such as `completed_at` for an in-progress envelope) are returned as `null`.
      responses:
        '200':
          description: The envelope was retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope.Envelope'
        4XX:
          $ref: '#/components/responses/Shared.ClientError'
        5XX:
          $ref: '#/components/responses/Shared.ServerError'
    patch:
      operationId: UpdateEnvelope
      summary: Update an envelope
      x-audience: public
      tags:
        - Envelopes
      description: |
        Updates an envelope by setting the values of the parameters passed. Any parameters not provided are left unchanged.

        Currently, only the `label` parameter can be updated. The label is for internal use only and is not shown to recipients. You can update the label regardless of the envelope's status.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                label:
                  $ref: '#/components/schemas/Envelope.Label'
      responses:
        '200':
          description: The envelope was updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope.Envelope'
        '422':
          $ref: '#/components/responses/Shared.ValidationError'
        4XX:
          $ref: '#/components/responses/Shared.ClientError'
        5XX:
          $ref: '#/components/responses/Shared.ServerError'
    delete:
      operationId: DeleteEnvelope
      summary: Delete an envelope
      x-audience: public
      tags:
        - Envelopes
      description: |
        Permanently deletes an envelope. The envelope immediately becomes inaccessible through the API.

        Only envelopes with status `canceled`, `completed`, or `failed` can be deleted. To delete an envelope that is `processing` or `in_progress`, cancel it first using the Cancel Envelope endpoint.

        Deleted envelopes can be recovered via a support request within 14 days. After 14 days, the data is permanently removed.
      responses:
        '204':
          description: The envelope was deleted successfully.
        4XX:
          $ref: '#/components/responses/Shared.ClientError'
        5XX:
          $ref: '#/components/responses/Shared.ServerError'
  /envelopes/{envelopeId}/cancel:
    parameters:
      - $ref: '#/components/parameters/EnvelopeId'
    post:
      operationId: CancelEnvelope
      summary: Cancel an envelope
      x-audience: public
      tags:
        - Envelopes
      description: |
        Cancels an envelope, immediately halting all signing activity. This action is irreversible and permanent.

        Only envelopes with status `in_progress` can be canceled. Once canceled, the envelope's status changes to `canceled` and recipients can no longer access the signing ceremony.

        An optional `reason` can be provided for internal tracking. The reason is included in the `envelope.canceled` webhook event but is not shown to recipients.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  $ref: '#/components/schemas/Envelope.CancelReason'
      responses:
        '200':
          description: The envelope was canceled successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope.Envelope'
        '422':
          $ref: '#/components/responses/Shared.ValidationError'
        4XX:
          $ref: '#/components/responses/Shared.ClientError'
        5XX:
          $ref: '#/components/responses/Shared.ServerError'
  /envelopes/{envelopeId}/events:
    parameters:
      - $ref: '#/components/parameters/EnvelopeId'
    get:
      operationId: ListEnvelopeEvents
      summary: List envelope events
      x-audience: public
      tags:
        - Events
      description: |
        Returns a list of events for a specific envelope. Events are sorted by timestamp, with the most recent appearing first.

        Results include envelope events, recipient events, and deliverable events associated with this envelope. Use the `type` query parameter to filter by a specific event type.

        The response is paginated. Use the `links.next` and `links.previous` URLs to navigate between pages.
      parameters:
        - $ref: '#/components/parameters/EnvelopeEventType'
        - $ref: '#/components/parameters/PaginationLimit'
      responses:
        '200':
          description: The list of envelope events was retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  links:
                    $ref: '#/components/schemas/Shared.PaginationLinks'
                  data:
                    type: array
                    description: An array of envelope events.
                    items:
                      $ref: '#/components/schemas/Event.EnvelopeContextEvent'
        4XX:
          $ref: '#/components/responses/Shared.ClientError'
        5XX:
          $ref: '#/components/responses/Shared.ServerError'
  /envelopes/{envelopeId}/deliverables:
    parameters:
      - $ref: '#/components/parameters/EnvelopeId'
    post:
      operationId: CreateDeliverable
      summary: Create a deliverable
      x-audience: public
      tags:
        - Deliverables
      description: |
        Creates a new deliverable from a completed envelope. The envelope must have a status of `completed`.

        Use this endpoint to generate additional deliverables after an envelope completes. For example, you might create a simple deliverable containing only specific documents, or a password-protected copy for secure distribution.

        The deliverable starts in `processing` status and transitions to `generated` once the PDF is ready. This usually takes a few seconds. Subscribe to the `deliverable.generated` webhook to be notified when the deliverable is available for download.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Deliverable.DeliverableInput'
      responses:
        '201':
          description: The deliverable was created successfully.
          headers:
            Location:
              $ref: '#/components/headers/Location'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Deliverable.Deliverable'
        '422':
          $ref: '#/components/responses/Shared.ValidationError'
        4XX:
          $ref: '#/components/responses/Shared.ClientError'
        5XX:
          $ref: '#/components/responses/Shared.ServerError'
    get:
      operationId: ListEnvelopeDeliverables
      summary: List deliverables
      x-audience: public
      tags:
        - Deliverables
      description: |-
        Returns a list of deliverables for an envelope. Each envelope has at least one deliverable created automatically when the envelope completes. Additional deliverables may exist if created via the Create Deliverable endpoint.

        The deliverables are sorted chronologically by creation date, with the earliest created deliverable appearing first.
      parameters:
        - $ref: '#/components/parameters/PaginationLimit'
      responses:
        '200':
          description: The list of deliverables was retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  links:
                    $ref: '#/components/schemas/Shared.PaginationLinks'
                  data:
                    type: array
                    description: An array of deliverables.
                    items:
                      $ref: '#/components/schemas/Deliverable.Deliverable'
        4XX:
          $ref: '#/components/responses/Shared.ClientError'
        5XX:
          $ref: '#/components/responses/Shared.ServerError'
  /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.

        Use 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).
      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.

        Use this when a recipient can no longer complete the envelope — for example, after a hard bounce or if the wrong person was assigned.

        Recipients 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.
      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}/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.

        Use this endpoint to create a ceremony after the envelope has been created, or to replace an existing ceremony with different authentication settings.

        The response includes the ceremony configuration and, when applicable, the ceremony URL. The `url` property is populated when the authentication method is `email_code` or `custom`. For `email_link` authentication, SignatureAPI delivers the URL by email and the `url` property is `null`.
      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'
  /recipients/{recipientId}/events:
    parameters:
      - $ref: '#/components/parameters/RecipientId'
    get:
      operationId: ListRecipientEvents
      summary: List recipient events
      x-audience: public
      tags:
        - Events
      description: |
        Returns a list of events for a specific recipient. Events are sorted by timestamp, with the most recent appearing first.

        Results include only recipient events, such as delivery, signing, and bounce events. Use the `type` query parameter to filter by a specific event type.

        The response is paginated. Use the `links.next` and `links.previous` URLs to navigate between pages.
      parameters:
        - $ref: '#/components/parameters/RecipientEventType'
        - $ref: '#/components/parameters/PaginationLimit'
      responses:
        '200':
          description: The list of recipient events was retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  links:
                    $ref: '#/components/schemas/Shared.PaginationLinks'
                  data:
                    type: array
                    description: An array of recipient events.
                    items:
                      $ref: '#/components/schemas/Event.RecipientEvent'
        4XX:
          $ref: '#/components/responses/Shared.ClientError'
        5XX:
          $ref: '#/components/responses/Shared.ServerError'
  /deliverables/{deliverableId}:
    parameters:
      - $ref: '#/components/parameters/DeliverableId'
    get:
      operationId: GetDeliverable
      summary: Retrieve a deliverable
      x-audience: public
      tags:
        - Deliverables
      description: |
        Retrieves the details of a deliverable, including its current status and download URL.

        When the deliverable status is `generated`, the response includes a `url` field with a download link. By default, this is a pre-signed URL that expires after 1 hour. Call this endpoint again to get a fresh URL if the previous one has expired.
      responses:
        '200':
          description: The deliverable was retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Deliverable.Deliverable'
        4XX:
          $ref: '#/components/responses/Shared.ClientError'
        5XX:
          $ref: '#/components/responses/Shared.ServerError'
  /events:
    get:
      operationId: ListEvents
      summary: List all events
      x-audience: public
      tags:
        - Events
      description: |
        Returns a list of all events across your account. Events are sorted by timestamp, with the most recent appearing first.

        Results include envelope, recipient, deliverable, and sender events. Use the `type` query parameter to filter by a specific event type.

        The response is paginated. Use the `links.next` and `links.previous` URLs to navigate between pages.
      parameters:
        - $ref: '#/components/parameters/EventType'
        - $ref: '#/components/parameters/PaginationLimit'
      responses:
        '200':
          description: The list of events was retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  links:
                    $ref: '#/components/schemas/Shared.PaginationLinks'
                  data:
                    type: array
                    description: An array of events.
                    items:
                      $ref: '#/components/schemas/Event.Event'
        4XX:
          $ref: '#/components/responses/Shared.ClientError'
        5XX:
          $ref: '#/components/responses/Shared.ServerError'
  /uploads:
    post:
      operationId: CreateUpload
      x-audience: public
      tags:
        - Uploads
      summary: Create an Upload
      description: |
        Uploads a file to SignatureAPI for use as a document source in an envelope.

        The upload is **temporary** and automatically deleted after **24 hours**. Send the raw file bytes in the request body with the appropriate `Content-Type` header. Maximum file size is **5 MB**.

        The response includes a `url` field that can be used anywhere a file URL is accepted, such as in the `document.url` field when adding documents to an envelope.

        To store a **permanent file** that can be reused, use the [Store Upload](/docs/v1/store-upload) endpoint or the file library in your dashboard.

        **Accepted media types:**

        | Media Type                                                                | Format |
        |---------------------------------------------------------------------------|--------|
        | `application/pdf`                                                         | `pdf`  |
        | `application/vnd.openxmlformats-officedocument.wordprocessingml.document` | `docx` |
        | `image/png`                                                               | `png`  |
      requestBody:
        required: true
        content:
          application/pdf:
            schema:
              type: string
              format: binary
              maxLength: 5242880
              title: PDF File
              description: The raw binary content of the PDF file to upload. Maximum 5 MB.
          application/vnd.openxmlformats-officedocument.wordprocessingml.document:
            schema:
              type: string
              format: binary
              maxLength: 5242880
              title: DOCX File
              description: The raw binary content of the DOCX file to upload. Maximum 5 MB.
          image/png:
            schema:
              type: string
              format: binary
              maxLength: 5242880
              title: PNG Image
              description: The raw binary content of the PNG image to upload. Maximum 5 MB.
      responses:
        '201':
          description: The upload was created successfully.
          headers:
            Location:
              $ref: '#/components/headers/Location'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Upload.TemporaryUpload'
              examples:
                pdf:
                  summary: PDF upload
                  value:
                    id: upl_1sAAaVfabdt0esVjmSTmLA
                    retention: temporary
                    url: https://api.signatureapi.com/v1/uploads/upl_1sAAaVfabdt0esVjmSTmLA
                    sha_256: 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
                    size: 102400
                    format: pdf
                    created_at: '2025-12-30T12:00:00.000Z'
                    expires_at: '2025-12-31T12:00:00.000Z'
                docx:
                  summary: DOCX upload
                  value:
                    id: upl_3joO7lxE8HVhOZmkCHFCxK
                    retention: temporary
                    url: https://api.signatureapi.com/v1/uploads/upl_3joO7lxE8HVhOZmkCHFCxK
                    sha_256: abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789
                    size: 234567
                    format: docx
                    created_at: '2025-12-30T12:00:00.000Z'
                    expires_at: '2025-12-31T12:00:00.000Z'
                png:
                  summary: PNG upload
                  value:
                    id: upl_7kBBcD2eF3gHiJkLmNoPqR
                    retention: temporary
                    url: https://api.signatureapi.com/v1/uploads/upl_7kBBcD2eF3gHiJkLmNoPqR
                    sha_256: fedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210
                    size: 51200
                    format: png
                    created_at: '2025-12-30T12:00:00.000Z'
                    expires_at: '2025-12-31T12:00:00.000Z'
        '422':
          $ref: '#/components/responses/Shared.ValidationError'
        4XX:
          $ref: '#/components/responses/Shared.ClientError'
        5XX:
          $ref: '#/components/responses/Shared.ServerError'
  /uploads/{uploadId}:
    parameters:
      - $ref: '#/components/parameters/UploadId'
    get:
      operationId: GetUpload
      summary: Retrieve an upload
      x-audience: public
      tags:
        - Uploads
      description: |
        Retrieves the metadata of an existing upload. Returns details such as the file format, size, SHA-256 hash, and retention type.

        This endpoint returns upload metadata only. The file content cannot be downloaded through the API.
      responses:
        '200':
          description: The upload was retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Upload.Upload'
              examples:
                temporary:
                  summary: Temporary upload
                  value:
                    id: upl_1sAAaVfabdt0esVjmSTmLA
                    retention: temporary
                    url: https://api.signatureapi.com/v1/uploads/upl_1sAAaVfabdt0esVjmSTmLA
                    sha_256: 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
                    size: 102400
                    format: pdf
                    created_at: '2025-12-30T12:00:00.000Z'
                    expires_at: '2025-12-31T12:00:00.000Z'
                permanent:
                  summary: Permanent upload
                  value:
                    id: upl_3joO7lxE8HVhOZmkCHFCxK
                    retention: permanent
                    key: contract-template-v2
                    url: https://api.signatureapi.com/v1/uploads/upl_3joO7lxE8HVhOZmkCHFCxK
                    sha_256: abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789
                    size: 234567
                    format: docx
                    created_at: '2025-12-30T12:00:00.000Z'
        4XX:
          $ref: '#/components/responses/Shared.ClientError'
        5XX:
          $ref: '#/components/responses/Shared.ServerError'
  /uploads/{uploadId}/store:
    parameters:
      - $ref: '#/components/parameters/UploadId'
    post:
      operationId: StoreUpload
      summary: Store an upload
      description: |
        Converts a temporary upload into a permanent upload. The file is moved to permanent storage and will no longer expire. A unique `key` is required to identify the permanent upload.
      x-audience: public
      tags:
        - Uploads
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                key:
                  $ref: '#/components/schemas/Upload.Key'
              required:
                - key
            examples:
              store:
                summary: Store with a key
                value:
                  key: contract-template-v2
      responses:
        '200':
          description: The upload was stored successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Upload.PermanentUpload'
              examples:
                stored:
                  summary: Upload stored permanently
                  value:
                    id: upl_1sAAaVfabdt0esVjmSTmLA
                    retention: permanent
                    key: contract-template-v2
                    url: https://api.signatureapi.com/v1/uploads/upl_1sAAaVfabdt0esVjmSTmLA
                    sha_256: 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
                    size: 102400
                    format: pdf
                    created_at: '2025-12-30T12:00:00.000Z'
        '422':
          $ref: '#/components/responses/Shared.ValidationError'
        4XX:
          $ref: '#/components/responses/Shared.ClientError'
        5XX:
          $ref: '#/components/responses/Shared.ServerError'
  /senders:
    post:
      operationId: CreateSender
      summary: Create a sender
      x-audience: public
      tags:
        - Senders
      description: |
        Registers a new sender email address and starts the verification process. SignatureAPI sends a verification email to the provided address. The sender is returned with `pending_verification` status.

        Once the email owner clicks the confirmation link, the sender status changes to `verified` and can be used on envelopes. SignatureAPI sends signing requests to recipients on behalf of verified senders. Listen for the `sender.verified` or `sender.failed` webhook events to track the outcome.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Sender.SenderInput'
      responses:
        '201':
          description: A sender was created successfully.
          headers:
            Location:
              $ref: '#/components/headers/Location'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sender.Sender'
        '422':
          $ref: '#/components/responses/Shared.ValidationError'
        4XX:
          $ref: '#/components/responses/Shared.ClientError'
        5XX:
          $ref: '#/components/responses/Shared.ServerError'
  /senders/{senderId}:
    parameters:
      - $ref: '#/components/parameters/SenderId'
    get:
      operationId: GetSender
      summary: Retrieve a Sender
      x-audience: public
      tags:
        - Senders
      description: |
        Retrieves the details of a sender. Use this endpoint to check the current verification status of a sender after creation.
      responses:
        '200':
          description: The sender was retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sender.Sender'
        '422':
          $ref: '#/components/responses/Shared.ValidationError'
        4XX:
          $ref: '#/components/responses/Shared.ClientError'
        5XX:
          $ref: '#/components/responses/Shared.ServerError'
    delete:
      operationId: DeleteSender
      summary: Delete a sender
      x-audience: public
      tags:
        - Senders
      description: |
        Deletes a sender. Once deleted, this email address can no longer be used on new envelopes. Envelopes already sent with this sender are not affected.
      responses:
        '204':
          description: The sender was deleted successfully.
        4XX:
          $ref: '#/components/responses/Shared.ClientError'
        5XX:
          $ref: '#/components/responses/Shared.ServerError'
webhooks:
  envelope.created:
    post:
      operationId: envelope.created
      summary: Envelope created event
      tags:
        - Webhooks
      description: |
        Fired when a new envelope is created. The envelope is in `processing` status at this point and has not yet been sent to recipients.

        Use this event to record that a signing process has been initiated in your system.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Event.EnvelopeCreated'
            example:
              id: evt_yA80uuM4c90EbmxFuOC8Xv5
              type: envelope.created
              timestamp: '2022-01-01T00:00:00Z'
              data:
                envelope_id: 5e5ace5e-bd1e-4d5a-bb1f-6a2b2e42cd13
                object_type: envelope
                object_id: 5e5ace5e-bd1e-4d5a-bb1f-6a2b2e42cd13
                envelope_metadata:
                  IntegrationId: '123456'
                  IntegrationName: My Integration
      responses:
        '200':
          description: Acknowledgment of receipt
  envelope.started:
    post:
      operationId: envelope.started
      summary: Envelope Started Webhook
      tags:
        - Webhooks
      description: |
        Fired when an envelope transitions from `processing` to `in_progress`. At this point, the envelope has been prepared and recipients are being notified.

        For sequential routing, the first recipient receives the signing request. For parallel routing, all recipients receive it at the same time.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Event.EnvelopeStarted'
            example:
              id: evt_yA80uuM4c90EbmxFuOC8Xv5
              type: envelope.started
              timestamp: '2022-01-01T00:00:00Z'
              data:
                envelope_id: 5e5ace5e-bd1e-4d5a-bb1f-6a2b2e42cd13
                object_type: envelope
                object_id: 5e5ace5e-bd1e-4d5a-bb1f-6a2b2e42cd13
                envelope_metadata:
                  IntegrationId: '123456'
                  IntegrationName: My Integration
      responses:
        '200':
          description: Acknowledgment of receipt
  envelope.completed:
    post:
      operationId: envelope.completed
      summary: Envelope Completed Webhook
      tags:
        - Webhooks
      description: |
        Fired when all recipients have completed their part and the envelope transitions to `completed` status. A deliverable containing the signed documents has been generated.

        Use this event to trigger downstream workflows such as storing signed documents, updating records, or notifying your team.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Event.EnvelopeCompleted'
            example:
              id: evt_yA80uuM4c90EbmxFuOC8Xv5
              type: envelope.completed
              timestamp: '2022-01-01T00:00:00Z'
              data:
                envelope_id: 5e5ace5e-bd1e-4d5a-bb1f-6a2b2e42cd13
                object_type: envelope
                object_id: 5e5ace5e-bd1e-4d5a-bb1f-6a2b2e42cd13
                envelope_metadata:
                  IntegrationId: '123456'
                  IntegrationName: My Integration
      responses:
        '200':
          description: Acknowledgment of receipt
  envelope.failed:
    post:
      operationId: envelope.failed
      summary: Envelope Failed Webhook
      tags:
        - Webhooks
      description: |
        Fired when an envelope encounters an internal error and transitions to `failed` status. The event payload includes a `detail` field with a human-readable explanation of the failure.

        Envelope failures are very rare and automatically trigger an alert to the SignatureAPI team. No action is typically required on your part.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Event.EnvelopeFailed'
            example:
              id: evt_yA80uuM4c90EbmxFuOC8Xv5
              type: envelope.failed
              timestamp: '2022-01-01T00:00:00Z'
              data:
                envelope_id: 5e5ace5e-bd1e-4d5a-bb1f-6a2b2e42cd13
                object_type: envelope
                object_id: 5e5ace5e-bd1e-4d5a-bb1f-6a2b2e42cd13
                detail: 'Error processing envelope for recipient at index: 1'
                envelope_metadata:
                  IntegrationId: '123456'
                  IntegrationName: My Integration
      responses:
        '200':
          description: Acknowledgment of receipt
  envelope.canceled:
    post:
      operationId: envelope.canceled
      summary: Envelope Canceled Webhook
      tags:
        - Webhooks
      description: |
        Fired when an envelope is canceled via the Cancel Envelope endpoint. The envelope transitions to `canceled` status and all signing activity stops permanently.

        The event payload includes an optional `reason` field if one was provided when the envelope was canceled.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Event.EnvelopeCanceled'
            example:
              id: evt_yA80uuM4c90EbmxFuOC8Xv5
              type: envelope.canceled
              timestamp: '2022-01-01T00:00:00Z'
              data:
                envelope_id: 5e5ace5e-bd1e-4d5a-bb1f-6a2b2e42cd13
                object_type: envelope
                object_id: 5e5ace5e-bd1e-4d5a-bb1f-6a2b2e42cd13
                reason: Not ready to sign
                envelope_metadata:
                  IntegrationId: '123456'
                  IntegrationName: My Integration
      responses:
        '200':
          description: Acknowledgment of receipt
  recipient.released:
    post:
      operationId: recipient.released
      summary: Recipient Released Webhook
      tags:
        - Webhooks
      description: |
        Fired when a recipient becomes ready to receive an invitation. The recipient's status changes to `pending`.

        This happens after all previous recipients in the routing order have completed, or immediately for the first recipient when the envelope starts processing.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Event.RecipientReleased'
            example:
              id: evt_yA80uuM4c90EbmxFuOC8Xv5
              type: recipient.released
              timestamp: '2022-01-01T00:00:00Z'
              data:
                envelope_id: 5e5ace5e-bd1e-4d5a-bb1f-6a2b2e42cd13
                object_type: recipient
                object_id: re_7vWMHIEuIIit8IRuKgtb61
                recipient_type: signer
                recipient_key: tenant
                envelope_metadata:
                  IntegrationId: '123456'
                  IntegrationName: My Integration
      responses:
        '200':
          description: Acknowledgment of receipt
  recipient.sent:
    post:
      operationId: recipient.sent
      summary: Recipient Sent Webhook
      tags:
        - Webhooks
      description: |
        Fired when the invitation email is sent to a recipient. The recipient's status changes to `sent`.

        This event only fires for recipients whose ceremony uses `email_link` authentication, because that is the only case where SignatureAPI sends the invitation email.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Event.RecipientSent'
            example:
              id: evt_yA80uuM4c90EbmxFuOC8Xv5
              type: recipient.sent
              timestamp: '2022-01-01T00:00:00Z'
              data:
                envelope_id: 5e5ace5e-bd1e-4d5a-bb1f-6a2b2e42cd13
                object_type: recipient
                object_id: re_7vWMHIEuIIit8IRuKgtb61
                recipient_type: signer
                recipient_key: tenant
                envelope_metadata:
                  IntegrationId: '123456'
                  IntegrationName: My Integration
      responses:
        '200':
          description: Acknowledgment of receipt
  recipient.accessed:
    post:
      operationId: recipient.accessed
      summary: Recipient Accessed Webhook
      tags:
        - Webhooks
      description: |
        Fired when a recipient opens the ceremony URL. Includes the recipient's `ip` address, `user_agent`, and `session_id`.

        To reduce duplicate events, this fires at most once every 60 seconds for the same IP address and user agent combination. The recipient has not yet authenticated at this point.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Event.RecipientAccessed'
            example:
              id: evt_yA80uuM4c90EbmxFuOC8Xv5
              type: recipient.accessed
              timestamp: '2022-01-01T00:00:00Z'
              data:
                envelope_id: 5e5ace5e-bd1e-4d5a-bb1f-6a2b2e42cd13
                object_type: recipient
                object_id: re_7vWMHIEuIIit8IRuKgtb61
                recipient_type: signer
                recipient_key: tenant
                ip: 123.122.990.22
                user_agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36
                session_id: ses_2X6eHBCL84MDGrLQX0mHI72
                envelope_metadata:
                  IntegrationId: '123456'
                  IntegrationName: My Integration
      responses:
        '200':
          description: Acknowledgment of receipt
  recipient.identity_verification_started:
    post:
      operationId: recipient.identity_verification_started
      summary: Recipient Identity Verification Started Webhook
      tags:
        - Webhooks
      description: |
        Fired when a recipient is sent to the identity verification provider. Includes the verification `method` and the `provider` handling the check.

        Nothing is proven at this point. Wait for `recipient.identity_verified` or `recipient.identity_rejected` for the outcome.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Event.RecipientIdentityVerificationStarted'
            example:
              id: evt_yA80uuM4c90EbmxFuOC8Xv5
              type: recipient.identity_verification_started
              timestamp: '2022-01-01T00:00:00Z'
              data:
                envelope_id: 5e5ace5e-bd1e-4d5a-bb1f-6a2b2e42cd13
                object_type: recipient
                object_id: re_7vWMHIEuIIit8IRuKgtb61
                recipient_type: signer
                recipient_key: tenant
                method: document_selfie
                provider: stub
                envelope_metadata:
                  IntegrationId: '123456'
                  IntegrationName: My Integration
      responses:
        '200':
          description: Acknowledgment of receipt
  recipient.identity_verified:
    post:
      operationId: recipient.identity_verified
      summary: Recipient Identity Verified Webhook
      tags:
        - Webhooks
      description: |
        Fired when the identity verification provider confirms the recipient's identity. Includes the verification `method`, the `provider`, and the `evidence_reference` you can quote back to the provider to retrieve the underlying proof.

        The recipient continues into the ceremony after this event. The evidence reference also appears in the envelope audit log.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Event.RecipientIdentityVerified'
            example:
              id: evt_yA80uuM4c90EbmxFuOC8Xv5
              type: recipient.identity_verified
              timestamp: '2022-01-01T00:00:00Z'
              data:
                envelope_id: 5e5ace5e-bd1e-4d5a-bb1f-6a2b2e42cd13
                object_type: recipient
                object_id: re_7vWMHIEuIIit8IRuKgtb61
                recipient_type: signer
                recipient_key: tenant
                method: document_selfie
                provider: stub
                evidence_reference: stub-9f2c1f6a2e6b4d1f9c0a
                envelope_metadata:
                  IntegrationId: '123456'
                  IntegrationName: My Integration
      responses:
        '200':
          description: Acknowledgment of receipt
  recipient.identity_rejected:
    post:
      operationId: recipient.identity_rejected
      summary: Recipient Identity Rejected Webhook
      tags:
        - Webhooks
      description: |
        Fired when the identity verification provider does not confirm the recipient's identity. Includes the verification `method`, the `provider`, and the `evidence_reference` you can quote back to the provider.

        The recipient can start the verification again until the attempt cap is reached, so this event can fire more than once for the same recipient.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Event.RecipientIdentityRejected'
            example:
              id: evt_yA80uuM4c90EbmxFuOC8Xv5
              type: recipient.identity_rejected
              timestamp: '2022-01-01T00:00:00Z'
              data:
                envelope_id: 5e5ace5e-bd1e-4d5a-bb1f-6a2b2e42cd13
                object_type: recipient
                object_id: re_7vWMHIEuIIit8IRuKgtb61
                recipient_type: signer
                recipient_key: tenant
                method: document_selfie
                provider: stub
                evidence_reference: stub-9f2c1f6a2e6b4d1f9c0a
                envelope_metadata:
                  IntegrationId: '123456'
                  IntegrationName: My Integration
      responses:
        '200':
          description: Acknowledgment of receipt
  recipient.viewed:
    post:
      operationId: recipient.viewed
      summary: Recipient Viewed Webhook
      tags:
        - Webhooks
      description: |
        Fired when a recipient has authenticated and the documents are displayed in the ceremony. This confirms the recipient has passed any authentication steps and can now view the documents.

        Includes a `session_id` to correlate with other events in the same ceremony session.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Event.RecipientViewed'
            example:
              id: evt_yA80uuM4c90EbmxFuOC8Xv5
              type: recipient.viewed
              timestamp: '2022-01-01T00:00:00Z'
              data:
                envelope_id: 5e5ace5e-bd1e-4d5a-bb1f-6a2b2e42cd13
                object_type: recipient
                object_id: re_7vWMHIEuIIit8IRuKgtb61
                recipient_type: signer
                recipient_key: tenant
                session_id: ses_2X6eHBCL84MDGrLQX0mHI72
                envelope_metadata:
                  IntegrationId: '123456'
                  IntegrationName: My Integration
      responses:
        '200':
          description: Acknowledgment of receipt
  recipient.completed:
    post:
      operationId: recipient.completed
      summary: Recipient Completed Webhook
      tags:
        - Webhooks
      description: |
        Fired when a recipient finishes all required actions in the ceremony. The recipient's status changes to `completed`.

        For signers, this means they have signed and finalized. For approvers and preparers, this means they have reviewed and submitted their inputs. Includes a `session_id` to correlate with other events in the same ceremony session.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Event.RecipientCompleted'
            example:
              id: evt_yA80uuM4c90EbmxFuOC8Xv5
              type: recipient.completed
              timestamp: '2022-01-01T00:00:00Z'
              data:
                envelope_id: 5e5ace5e-bd1e-4d5a-bb1f-6a2b2e42cd13
                object_type: recipient
                object_id: re_7vWMHIEuIIit8IRuKgtb61
                recipient_type: signer
                recipient_key: tenant
                session_id: ses_2X6eHBCL84MDGrLQX0mHI72
                envelope_metadata:
                  IntegrationId: '123456'
                  IntegrationName: My Integration
      responses:
        '200':
          description: Acknowledgment of receipt
  recipient.rejected:
    post:
      operationId: recipient.rejected
      summary: Recipient Rejected Webhook
      tags:
        - Webhooks
      description: |
        Fired when a recipient declines to complete the envelope. The recipient's status changes to `rejected`.

        The `reason` field contains the explanation the recipient provided, if any. When a recipient rejects, the entire envelope is voided. Includes a `session_id` to correlate with other events in the same ceremony session.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Event.RecipientRejected'
            example:
              id: evt_yA80uuM4c90EbmxFuOC8Xv5
              type: recipient.rejected
              timestamp: '2022-01-01T00:00:00Z'
              data:
                envelope_id: 5e5ace5e-bd1e-4d5a-bb1f-6a2b2e42cd13
                object_type: recipient
                object_id: re_7vWMHIEuIIit8IRuKgtb61
                recipient_type: signer
                recipient_key: tenant
                reason: Not the terms we agreed to on June
                session_id: ses_2X6eHBCL84MDGrLQX0mHI72
                envelope_metadata:
                  IntegrationId: '123456'
                  IntegrationName: My Integration
      responses:
        '200':
          description: Acknowledgment of receipt
  recipient.soft_bounced:
    post:
      operationId: recipient.soft_bounced
      summary: Recipient Soft Bounced Webhook
      tags:
        - Webhooks
      description: |
        Fired when the invitation email is temporarily undeliverable. The recipient's status changes to `soft_bounced`.

        Common causes include a full mailbox or a temporary server issue. The `detail` field contains the bounce reason from the remote email server. You can use the Resend Request endpoint to try again.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Event.RecipientSoftBounced'
            example:
              id: evt_yA80uuM4c90EbmxFuOC8Xv5
              type: recipient.soft_bounced
              timestamp: '2022-01-01T00:00:00Z'
              data:
                envelope_id: 5e5ace5e-bd1e-4d5a-bb1f-6a2b2e42cd13
                object_type: recipient
                object_id: re_7vWMHIEuIIit8IRuKgtb61
                recipient_type: signer
                recipient_key: tenant
                detail: 'Server 123.122.990.22 responded with: Mailbox Full'
                envelope_metadata:
                  IntegrationId: '123456'
                  IntegrationName: My Integration
      responses:
        '200':
          description: Acknowledgment of receipt
  recipient.hard_bounced:
    post:
      operationId: recipient.hard_bounced
      summary: Recipient Hard Bounced Webhook
      tags:
        - Webhooks
      description: |
        Fired when the invitation email is permanently undeliverable. The recipient's status changes to `hard_bounced`.

        Common causes include an invalid or nonexistent email address. The `detail` field contains the bounce reason from the remote email server. You cannot resend to this recipient. Use the Replace Recipient endpoint to assign a new person.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Event.RecipientHardBounced'
            example:
              id: evt_yA80uuM4c90EbmxFuOC8Xv5
              type: recipient.hard_bounced
              timestamp: '2022-01-01T00:00:00Z'
              data:
                envelope_id: 5e5ace5e-bd1e-4d5a-bb1f-6a2b2e42cd13
                object_type: recipient
                object_id: re_7vWMHIEuIIit8IRuKgtb61
                recipient_type: signer
                recipient_key: tenant
                detail: 'Server 123.122.990.22 responded with: Mailbox Full'
                envelope_metadata:
                  IntegrationId: '123456'
                  IntegrationName: My Integration
      responses:
        '200':
          description: Acknowledgment of receipt
  recipient.failed:
    post:
      operationId: recipient.failed
      summary: Recipient Failed Webhook
      tags:
        - Webhooks
      description: |
        Fired when an error prevents the invitation from being sent to a recipient. The recipient's status changes to `failed`.

        The `detail` field contains a description of the failure, such as the recipient's email being on a blocklist. You may need to use the Replace Recipient endpoint to assign a different person.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Event.RecipientFailed'
            example:
              id: evt_yA80uuM4c90EbmxFuOC8Xv5
              type: recipient.failed
              timestamp: '2022-01-01T00:00:00Z'
              data:
                envelope_id: 5e5ace5e-bd1e-4d5a-bb1f-6a2b2e42cd13
                object_type: recipient
                object_id: re_7vWMHIEuIIit8IRuKgtb61
                recipient_type: signer
                recipient_key: tenant
                detail: Recipient in email blocklist
                envelope_metadata:
                  IntegrationId: '123456'
                  IntegrationName: My Integration
      responses:
        '200':
          description: Acknowledgment of receipt
  recipient.replaced:
    post:
      operationId: recipient.replaced
      summary: Recipient Replaced Webhook
      tags:
        - Webhooks
      description: |
        Fired when a recipient is replaced with a new person via the Replace Recipient endpoint. The original recipient's status changes to `replaced`.

        The event includes `new_recipient_id` and `new_recipient_name` identifying the replacement recipient.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Event.RecipientReplaced'
            example:
              id: evt_yA80uuM4c90EbmxFuOC8Xv5
              type: recipient.replaced
              timestamp: '2022-01-01T00:00:00Z'
              data:
                envelope_id: 5e5ace5e-bd1e-4d5a-bb1f-6a2b2e42cd13
                object_type: recipient
                object_id: re_7vWMHIEuIIit8IRuKgtb61
                recipient_type: signer
                recipient_key: tenant
                new_recipient_id: re_5SfFjI3eVfDokAXXDSjJlz
                new_recipient_name: John Doe
                envelope_metadata:
                  IntegrationId: '123456'
                  IntegrationName: My Integration
      responses:
        '200':
          description: Acknowledgment of receipt
  recipient.resent:
    post:
      operationId: recipient.resent
      summary: Recipient Resent Webhook
      tags:
        - Webhooks
      description: |
        Fired when an invitation email is resent to a recipient via the Resend Request endpoint. The recipient's status remains `sent`.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Event.RecipientResent'
            example:
              id: evt_yA80uuM4c90EbmxFuOC8Xv5
              type: recipient.resent
              timestamp: '2022-01-01T00:00:00Z'
              data:
                envelope_id: 5e5ace5e-bd1e-4d5a-bb1f-6a2b2e42cd13
                object_type: recipient
                object_id: re_7vWMHIEuIIit8IRuKgtb61
                recipient_type: signer
                recipient_key: tenant
                envelope_metadata:
                  IntegrationId: '123456'
                  IntegrationName: My Integration
      responses:
        '200':
          description: Acknowledgment of receipt
  deliverable.generated:
    post:
      operationId: deliverable.generated
      summary: Deliverable generation success event
      tags:
        - Webhooks
      description: |
        Fired when a deliverable is successfully generated and ready for download. The event payload includes a `url` field with a pre-signed download link.

        This URL expires after 1 hour. If it has expired, retrieve a fresh URL by calling the Get Deliverable endpoint.

        Use this event to download and store signed documents in your system automatically.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Event.DeliverableGenerated'
            example:
              id: evt_yA80uuM4c90EbmxFuOC8Xv5
              type: deliverable.generated
              timestamp: '2022-01-01T00:00:00Z'
              data:
                envelope_id: 5e5ace5e-bd1e-4d5a-bb1f-6a2b2e42cd13
                object_type: deliverable
                object_id: del_4TpbrIB7ZB2ZNarCJQ8QYR
                deliverable_type: standard
                deliverable_name: hr_pack
                included_documents:
                  - contract
                  - byod_policy
                url: https://www.example.com/repository/audit-log.pdf
                envelope_metadata:
                  IntegrationId: '123456'
                  IntegrationName: My Integration
      responses:
        '200':
          description: Acknowledgment of receipt
  deliverable.failed:
    post:
      operationId: deliverable.failed
      summary: Deliverable generation failure event
      tags:
        - Webhooks
      description: |
        Fired when deliverable generation fails. The deliverable status is set to `failed`. The event payload includes a `detail` field with a human-readable explanation of the failure.

        This is a rare event. Support is notified automatically when it occurs.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Event.DeliverableFailed'
            example:
              id: evt_yA80uuM4c90EbmxFuOC8Xv5
              type: deliverable.failed
              timestamp: '2022-01-01T00:00:00Z'
              data:
                envelope_id: 5e5ace5e-bd1e-4d5a-bb1f-6a2b2e42cd13
                deliverable_type: standard
                deliverable_name: hr_pack
                included_documents:
                  - contract
                  - byod_policy
                object_type: deliverable
                object_id: del_4TpbrIB7ZB2ZNarCJQ8QYR
                detail: Recipient in email blocklist.
                envelope_metadata:
                  IntegrationId: '123456'
                  IntegrationName: My Integration
      responses:
        '200':
          description: Acknowledgment of receipt
  sender.created:
    post:
      operationId: sender.created
      summary: Sender created event
      tags:
        - Webhooks
      description: |
        Triggered when a new sender is created and the verification email is sent. The sender starts in `pending_verification` status. Listen for `sender.verified` or `sender.failed` to track the verification outcome.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Event.SenderCreated'
            example:
              id: evt_yA80uuM4c90EbmxFuOC8Xv5
              type: sender.created
              timestamp: '2025-01-01T00:00:00Z'
              data:
                object_type: sender
                object_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                email: john@example.com
      responses:
        '200':
          description: Acknowledgment of receipt
  sender.verified:
    post:
      operationId: sender.verified
      summary: Sender verified event
      tags:
        - Webhooks
      description: |
        Triggered when a sender completes email verification. The sender status is now `verified` and SignatureAPI can send signing requests on behalf of this email address.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Event.SenderVerified'
            example:
              id: evt_yA80uuM4c90EbmxFuOC8Xv5
              type: sender.verified
              timestamp: '2025-01-01T00:00:00Z'
              data:
                object_type: sender
                object_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                email: john@example.com
      responses:
        '200':
          description: Acknowledgment of receipt
  sender.failed:
    post:
      operationId: sender.failed
      summary: Sender failed event
      tags:
        - Webhooks
      description: |
        Triggered when sender email verification fails. This can happen due to a soft or hard bounce of the verification email, or because of an internal error. The `data.detail` field explains the reason for the failure.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Event.SenderFailed'
            example:
              id: evt_yA80uuM4c90EbmxFuOC8Xv5
              type: sender.failed
              timestamp: '2025-01-01T00:00:00Z'
              data:
                object_type: sender
                object_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                email: john@example.com
                detail: Verification email bounced
      responses:
        '200':
          description: Acknowledgment of receipt
  sender.deleted:
    post:
      operationId: sender.deleted
      summary: Sender deleted event
      tags:
        - Webhooks
      description: |
        Triggered when a sender is deleted. SignatureAPI can no longer send signing requests on behalf of this email address.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Event.SenderDeleted'
            example:
              id: evt_yA80uuM4c90EbmxFuOC8Xv5
              type: sender.deleted
              timestamp: '2025-01-01T00:00:00Z'
              data:
                object_type: sender
                object_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                email: john@example.com
      responses:
        '200':
          description: Acknowledgment of receipt
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.

        Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.
  schemas:
    Envelope.Status:
      x-schema-role: property
      x-schema-direction: output
      type: string
      enum:
        - processing
        - in_progress
        - completed
        - failed
        - canceled
      title: Envelope Status
      description: |
        The current status of the envelope in its lifecycle.

        - `processing` -- The envelope is being prepared. Documents are validated and recipients are notified.
        - `in_progress` -- The envelope has been sent to recipients and is waiting for all participants to complete.
        - `completed` -- All recipients have completed their part. A deliverable has been generated.
        - `failed` -- An internal error occurred during processing. Failures are rare and trigger automatic alerts.
        - `canceled` -- The signing process was intentionally stopped before completion.

        The typical progression is `processing` -> `in_progress` -> `completed`. An envelope can transition to `failed` from `processing`, or to `canceled` from `in_progress` via the Cancel Envelope endpoint.
      examples:
        - completed
    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.

        Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters.
      type: string
      pattern: ^[a-z][a-z0-9_]*$
      minLength: 1
      maxLength: 32
      examples:
        - sales
    Shared.PaginationLinks:
      x-schema-role: property
      x-schema-direction: output
      title: Pagination Links
      description: |
        Navigation links for cursor-based pagination. All list endpoints return results in reverse chronological order. Use the `next` and `previous` URLs to move between pages. Treat these URLs as opaque strings — do not parse or construct them yourself.
      type: object
      additionalProperties: false
      properties:
        next:
          type:
            - string
            - 'null'
          format: uri
          description: |
            A pre-built URL for fetching the next page of results. Returns `null` when you are on the last page. Send a GET request to this URL to load more results.
          example: https://api.signatureapi.com/v1/envelopes?cursor=seq_0thJdKRhN4&limit=20
        previous:
          type:
            - string
            - 'null'
          format: uri
          description: |
            A pre-built URL for fetching the previous page of results. Returns `null` when you are on the first page. Send a GET request to this URL to go back.
          example: https://api.signatureapi.com/v1/envelopes?cursor=seq_7yNl3c0t&limit=20
      required:
        - next
        - previous
    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
    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.

        Use 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.
      type:
        - string
        - 'null'
      minLength: 1
      maxLength: 500
      default: null
      examples:
        - 'Explorer Agreement #7772 Mr Spender'
    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.

        Metadata is included in all API responses and webhook payloads (in the `data.envelope_metadata` field), making it useful for correlating events with your records.

        Up to 10 keys are allowed. Keys can be up to 32 characters (letters, digits, and underscores). Values can be up to 1,000 characters.

        Use metadata only for ordinary business identifiers that are appropriate to store with an envelope.
      unevaluatedProperties: false
      maxProperties: 10
      default: {}
      additionalProperties:
        type: string
        minLength: 1
        maxLength: 1000
      propertyNames:
        type: string
        pattern: ^[a-zA-Z0-9_]*$
        minLength: 1
        maxLength: 32
      example:
        caseNumber: AB5555510
        customer_name: Doe Industries, LLC
    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.

        The message supports a subset of Markdown formatting:
        - `**bold**` for bold text
        - `*italic*` for italic text
        - `\n\n` for paragraph breaks
      minLength: 1
      maxLength: 2000
      default: null
      examples:
        - Thank you for accepting to be a Mars explorer! Please sign this agreement.
    Envelope.Mode:
      x-schema-role: property
      x-schema-direction: output
      type: string
      enum:
        - live
        - test
      title: Envelope Mode
      description: |
        The mode of the envelope, which determines its legal status and billing.

        - `live` -- Legally binding and billable. Created when using a live API key.
        - `test` -- Not legally binding and free of charge. Created when using a test API key.

        The mode is set automatically based on the API key used to create the envelope and cannot be changed afterward.
      examples:
        - live
    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.

        Choose 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.
      minLength: 1
      maxLength: 500
      examples:
        - Mars Exploration Agreement
    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.

        Topics 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.
      type: array
      maxItems: 10
      default: []
      items:
        $ref: '#/components/schemas/Envelope.Topic'
    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.

        The 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.
      maxLength: 2048
      default: null
      examples:
        - https://api.signatureapi.com/v1/uploads/upl_3joO7lxE8HVhOZmkCHFCxK
    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`).

        The color must have a contrast ratio of at least 4.5:1 against white, following [WCAG guidelines](https://www.w3.org/TR/WCAG21/). If the color does not meet this requirement, the API returns an error with a suggested compliant alternative.

        Does not affect input fields, checkboxes, or signature boxes. Defaults to `#2463eb` (blue) if not specified.
      examples:
        - '#2463eb'
      pattern: ^#[a-fA-F0-9]{6}$
      default: '#2463eb'
    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.

        Defaults 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
      examples:
        - noreply@signatureapi.com
        - support@example.com
    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.

        Use this for company disclaimers, privacy notices, or contact information.

        The footer supports a subset of Markdown formatting:
        - `**bold**` for bold text
        - `*italic*` for italic text
        - `\n\n` for paragraph breaks
      minLength: 1
      maxLength: 10000
      default: null
      examples:
        - This communication, including any attachments, is confidential and may contain privileged information; it is intended solely for the use of the designated recipient.
    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.

        - `left` -- Aligns the logo to the left.
        - `center` -- Centers the logo.
        - `right` -- Aligns the logo to the right.

        Defaults to `left` if not specified.
      examples:
        - left
    Envelope.Branding:
      x-schema-role: property
      x-schema-direction: output
      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.

        The following branding options are available:

        - **logo** -- A logo image displayed in the header of emails and the signing ceremony. Must be a PNG file uploaded to the Library.
        - **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`.
        - **email.footer** -- A custom footer appended to emails. Supports Markdown for bold, italic, and paragraph breaks. Useful for disclaimers or contact information.
        - **email.logo_position** -- Controls logo alignment in emails: `left`, `center`, or `right`. Defaults to `left`.
        - **email.from** -- The email address shown in the "From" field. Defaults to `noreply@signatureapi.com`. Custom domains require DNS configuration.
      properties:
        logo:
          $ref: '#/components/schemas/Envelope.BrandingLogo'
        accent_color:
          $ref: '#/components/schemas/Envelope.BrandingAccentColor'
        email:
          type: object
          additionalProperties: false
          properties:
            from:
              $ref: '#/components/schemas/Envelope.BrandingEmailFrom'
            footer:
              $ref: '#/components/schemas/Envelope.BrandingEmailFooter'
            logo_position:
              $ref: '#/components/schemas/Envelope.BrandingEmailLogoPosition'
          required:
            - from
            - footer
            - logo_position
      required:
        - logo
        - accent_color
        - email
    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`).

        If not specified, the account's default timezone is used.
      example: America/New_York
    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`).

        If not specified, the account's default timestamp format is used.
      example: MM/DD/YYYY HH:mm:ss
    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.

        Supported languages: `en` (English), `es` (Spanish), `fr` (French), `it` (Italian), `pt` (Portuguese), `de` (German), `zh` (Chinese Simplified), `hu` (Hungarian), `nl` (Dutch).

        If not specified, the account's default language will be used instead.
      examples:
        - en
    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.

        - `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.
        - `parallel` -- All recipients receive the envelope at the same time and can act in any order.

        Defaults to `sequential` if not specified.
      type: string
      default: sequential
      enum:
        - sequential
        - parallel
    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.

        - `none` -- No attestation. This is the default.
        - `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.
        - `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.
      type: string
      enum:
        - none
        - mx_nom151
        - br_icp_brasil
      default: none
    Document.Id:
      x-schema-role: property
      x-schema-direction: output
      title: Document Id
      description: The unique identifier of the document. Starts with `doc_`.
      type: string
      examples:
        - doc_kUlmphnFR6CFr6oChasgVb8
    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.

        Only lowercase letters, numbers, and underscores are allowed. Must start with a letter.

        If not provided, a key is generated automatically.
      type: string
      pattern: ^[a-z][a-z0-9_]*$
      minLength: 1
      maxLength: 32
      examples:
        - agreement
        - byod_policy
    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.

        If not provided, defaults to `null`.
      minLength: 1
      maxLength: 500
      default: null
      examples:
        - Exploration Agreement
    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.

        You can provide a URL from any hosting service, including Amazon S3, Google Cloud Storage, Azure Blob Storage, Cloudflare R2, Dropbox, and Google Drive.

        Alternatively, use the **Create Upload** endpoint to upload a file to SignatureAPI first, then use the returned `url` value here.
      maxLength: 2048
      examples:
        - https://www.example.com/agreement-template.docx
    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.

        - `pdf` -- Standard PDF file. Supports places via placeholders or fixed positions.
        - `docx` -- Microsoft Word file. Supports template fields for dynamic content in addition to places.
      enum:
        - pdf
        - docx
      examples:
        - pdf
    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.

        Keys 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: {}
      example:
        day: '31'
        month: December
        year: '2025'
        explorer:
          name: Jeff Spender
          company: ACME, Inc
    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
      example: 1
    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.

        For example, `360` is 5 inches from the top edge.
      type: number
      example: 144
    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.

        For example, `72` is 1 inch from the left edge.
      type: number
      example: 72
    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
      examples:
        - licensor_signs_here
    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
      examples:
        - billing_cycle:monthly
    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.

        Coordinates 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: '#/components/schemas/Document.FixedPositionPage'
        top:
          $ref: '#/components/schemas/Document.FixedPositionTop'
        left:
          $ref: '#/components/schemas/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: '#/components/schemas/Place.Key'
            - $ref: '#/components/schemas/Place.RadioGroupMemberKey'
      required:
        - page
        - top
        - left
        - place_key
    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.

        Use fixed positions as an alternative to embedding `[[place_key]]` placeholders in the document text.
      type: array
      items:
        $ref: '#/components/schemas/Document.FixedPosition'
      default: []
    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.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.

        The key must start with a lowercase letter and can contain lowercase letters, numbers, and underscores. Maximum 32 characters.
      type: string
      pattern: ^[a-z][a-z0-9_]*$
      minLength: 1
      maxLength: 32
      examples:
        - explorer
    Place.RecipientKey:
      x-schema-role: property
      x-schema-direction: any
      allOf:
        - $ref: '#/components/schemas/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.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
      examples:
        - 60
        - 40
    Place.SignaturePlace:
      x-schema-role: model
      x-schema-direction: output
      title: Signature Place
      description: |
        A **signature place** marks a location on a document where a recipient draws or types their signature.

        Each 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.

        The width is automatically calculated using a 5:2 ratio based on the height.
      type: object
      properties:
        key:
          $ref: '#/components/schemas/Place.Key'
        type:
          allOf:
            - $ref: '#/components/schemas/Place.Type'
            - const: signature
        recipient_key:
          $ref: '#/components/schemas/Place.RecipientKey'
        height:
          $ref: '#/components/schemas/Place.SignatureHeight'
      required:
        - key
        - type
        - recipient_key
        - height
    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
      examples:
        - 60
        - 25
    Place.InitialsPlace:
      x-schema-role: model
      x-schema-direction: output
      title: Initials Place
      description: |
        An **initials place** marks a location on a document where a recipient enters their initials.

        Each 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.

        The width equals the height.
      type: object
      properties:
        key:
          $ref: '#/components/schemas/Place.Key'
        type:
          allOf:
            - $ref: '#/components/schemas/Place.Type'
            - const: initials
        recipient_key:
          $ref: '#/components/schemas/Place.RecipientKey'
        height:
          $ref: '#/components/schemas/Place.InitialsHeight'
      required:
        - key
        - type
        - recipient_key
        - height
    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.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.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.
      examples:
        - 20
    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
      examples:
        - customer_email
    Place.CheckboxPlace:
      x-schema-role: model
      x-schema-direction: output
      title: Checkbox Place
      description: |
        A **checkbox place** marks a location on a document where a recipient checks or unchecks a box.

        Checkbox 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.

        Use `capture_as` to store the checkbox value in the envelope's captures for later retrieval.
      type: object
      properties:
        key:
          $ref: '#/components/schemas/Place.Key'
        type:
          allOf:
            - $ref: '#/components/schemas/Place.Type'
            - const: checkbox
        requirement:
          $ref: '#/components/schemas/Place.Requirement'
        recipient_key:
          $ref: '#/components/schemas/Place.RecipientKey'
        symbol:
          $ref: '#/components/schemas/Place.CheckboxSymbol'
        height:
          $ref: '#/components/schemas/Place.CheckboxHeight'
        capture_as:
          $ref: '#/components/schemas/Place.CaptureAs'
      required:
        - key
        - type
        - recipient_key
        - symbol
        - height
        - capture_as
    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
      examples:
        - John Doe
    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
      examples:
        - Enter your full legal name
    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.
      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.
          example: /^[a-z0-9]{1,10}$/
        - 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
      examples:
        - Please enter a valid 8-digit reference number
    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
      examples:
        - 12
        - 10
    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
      examples:
        - 200
    Place.TextInputPlace:
      x-schema-role: model
      x-schema-direction: output
      title: Text Input Place
      description: |
        A **text input place** marks a location on a document where a recipient types free-form text.

        Text 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.

        Input 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.

        Use `capture_as` to store the entered text in the envelope's captures for later retrieval.
      type: object
      properties:
        key:
          $ref: '#/components/schemas/Place.Key'
        type:
          allOf:
            - $ref: '#/components/schemas/Place.Type'
            - const: text_input
        recipient_key:
          $ref: '#/components/schemas/Place.RecipientKey'
        requirement:
          $ref: '#/components/schemas/Place.Requirement'
        prompt:
          $ref: '#/components/schemas/Place.Prompt'
        hint:
          $ref: '#/components/schemas/Place.Hint'
        capture_as:
          $ref: '#/components/schemas/Place.CaptureAs'
        format:
          $ref: '#/components/schemas/Place.TextInputFormat'
        format_message:
          $ref: '#/components/schemas/Place.TextInputFormatMessage'
        font_size:
          $ref: '#/components/schemas/Place.TextInputFontSize'
        width:
          $ref: '#/components/schemas/Place.TextInputWidth'
      required:
        - key
        - type
        - recipient_key
        - requirement
        - prompt
        - hint
        - capture_as
        - format
        - format_message
        - font_size
        - width
    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
      examples:
        - 20
    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
      examples:
        - 6
    Place.BoxedTextInputPlace:
      x-schema-role: model
      x-schema-direction: output
      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.

        Boxed text input places are available in envelopes with sequential signing. The `box_count` property controls how many character boxes are displayed.

        Use `capture_as` to store the entered text in the envelope's captures for later retrieval.
      type: object
      properties:
        key:
          $ref: '#/components/schemas/Place.Key'
        type:
          allOf:
            - $ref: '#/components/schemas/Place.Type'
            - const: boxed_text_input
        recipient_key:
          $ref: '#/components/schemas/Place.RecipientKey'
        requirement:
          $ref: '#/components/schemas/Place.Requirement'
        font_size:
          $ref: '#/components/schemas/Place.TextInputFontSize'
        height:
          $ref: '#/components/schemas/Place.TextInputHeight'
        width:
          $ref: '#/components/schemas/Place.TextInputWidth'
        box_count:
          $ref: '#/components/schemas/Place.BoxCount'
        prompt:
          $ref: '#/components/schemas/Place.Prompt'
        hint:
          $ref: '#/components/schemas/Place.Hint'
        capture_as:
          $ref: '#/components/schemas/Place.CaptureAs'
      required:
        - key
        - type
        - recipient_key
        - requirement
        - font_size
        - height
        - width
        - box_count
        - prompt
        - hint
        - capture_as
    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
      examples:
        - 5
    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
      examples:
        - 12
    Place.MultiLineTextInputPlace:
      x-schema-role: model
      x-schema-direction: output
      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.

        Multi-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`.

        Use `capture_as` to store the entered text in the envelope's captures for later retrieval.
      type: object
      properties:
        key:
          $ref: '#/components/schemas/Place.Key'
        type:
          allOf:
            - $ref: '#/components/schemas/Place.Type'
            - const: multiline_text_input
        recipient_key:
          $ref: '#/components/schemas/Place.RecipientKey'
        requirement:
          $ref: '#/components/schemas/Place.Requirement'
        prompt:
          $ref: '#/components/schemas/Place.Prompt'
        hint:
          $ref: '#/components/schemas/Place.Hint'
        capture_as:
          $ref: '#/components/schemas/Place.CaptureAs'
        font_size:
          $ref: '#/components/schemas/Place.TextInputFontSize'
        width:
          $ref: '#/components/schemas/Place.TextInputWidth'
        line_count:
          $ref: '#/components/schemas/Place.MultiLineTextInputLineCount'
        line_height:
          $ref: '#/components/schemas/Place.MultiLineTextInputLineHeight'
      required:
        - key
        - type
        - recipient_key
        - requirement
        - prompt
        - hint
        - capture_as
        - font_size
        - width
        - line_count
        - line_height
    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.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.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: '#/components/schemas/Place.DropdownPlaceCustomOptions'
        - $ref: '#/components/schemas/Place.DropdownPlacePredefinedOptions'
    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.

        If no match is found, a validation error is returned.
      type:
        - string
        - 'null'
      default: null
      examples:
        - United States
        - us
    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.

        When set to auto, the behavior is determined by the number of options:
        - `select` if there are 10 or fewer options
        - `combobox` if there are more than 10 options
      type: string
      enum:
        - auto
        - select
        - combobox
      default: auto
    Place.DropdownPlace:
      x-schema-role: model
      x-schema-direction: output
      title: Dropdown Place
      description: |
        A **dropdown place** marks a location on a document where a recipient selects from a list of options.

        Dropdown 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`.

        The `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.

        Use `capture_as` to store the selected value in the envelope's captures for later retrieval.
      type: object
      properties:
        key:
          $ref: '#/components/schemas/Place.Key'
        type:
          allOf:
            - $ref: '#/components/schemas/Place.Type'
            - const: dropdown
        recipient_key:
          $ref: '#/components/schemas/Place.RecipientKey'
        options:
          $ref: '#/components/schemas/Place.DropdownPlaceOptions'
        default:
          $ref: '#/components/schemas/Place.DropdownPlaceDefault'
        behavior:
          $ref: '#/components/schemas/Place.DropdownPlaceBehavior'
        requirement:
          $ref: '#/components/schemas/Place.Requirement'
        prompt:
          $ref: '#/components/schemas/Place.Prompt'
        hint:
          $ref: '#/components/schemas/Place.Hint'
        capture_as:
          $ref: '#/components/schemas/Place.CaptureAs'
        font_size:
          $ref: '#/components/schemas/Place.TextInputFontSize'
        width:
          $ref: '#/components/schemas/Place.TextInputWidth'
      required:
        - key
        - type
        - recipient_key
        - options
        - default
        - behavior
        - requirement
        - prompt
        - hint
        - capture_as
        - font_size
        - width
    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.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.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.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.

        If no match is found, a validation error is returned.
      type:
        - string
        - 'null'
      minLength: 1
      maxLength: 32
      default: null
      examples:
        - monthly
    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.
      examples:
        - 20
    Place.RadioGroupPlace:
      x-schema-role: model
      x-schema-direction: output
      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.

        Unlike 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.

        ### Options

        The `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.

        Provide `default` to preselect an option; its value must match one of the option `value`s.

        ### Positioning

        Options 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`.

        For 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`.

        Radio group places are available in envelopes with sequential signing.
      type: object
      properties:
        key:
          $ref: '#/components/schemas/Place.Key'
        type:
          allOf:
            - $ref: '#/components/schemas/Place.Type'
            - const: radio_group
        recipient_key:
          $ref: '#/components/schemas/Place.RecipientKey'
        options:
          $ref: '#/components/schemas/Place.RadioGroupPlaceOptions'
        symbol:
          $ref: '#/components/schemas/Place.RadioGroupSymbol'
        shape:
          $ref: '#/components/schemas/Place.RadioGroupShape'
        requirement:
          $ref: '#/components/schemas/Place.Requirement'
        default:
          $ref: '#/components/schemas/Place.RadioGroupPlaceDefault'
        capture_as:
          $ref: '#/components/schemas/Place.CaptureAs'
        height:
          $ref: '#/components/schemas/Place.RadioGroupHeight'
      required:
        - key
        - type
        - recipient_key
        - options
        - symbol
        - shape
        - requirement
        - default
        - capture_as
        - height
    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
      examples:
        - D MMM YYYY
        - YYYY-MM-DD
        - MM/DD/YYYY
    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
      examples:
        - 12
    Place.RecipientDatePlace:
      x-schema-role: model
      x-schema-direction: output
      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.

        Each 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.
      type: object
      properties:
        key:
          $ref: '#/components/schemas/Place.Key'
        type:
          allOf:
            - $ref: '#/components/schemas/Place.Type'
            - const: recipient_completed_date
        recipient_key:
          $ref: '#/components/schemas/Place.RecipientKey'
        date_format:
          $ref: '#/components/schemas/Place.DateFormat'
        font_size:
          $ref: '#/components/schemas/Place.FontSize'
      required:
        - key
        - type
        - recipient_key
        - date_format
        - font_size
    Place.EnvelopeDatePlace:
      x-schema-role: model
      x-schema-direction: output
      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.

        This 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.
      type: object
      properties:
        key:
          $ref: '#/components/schemas/Place.Key'
        type:
          allOf:
            - $ref: '#/components/schemas/Place.Type'
            - const: envelope_completed_date
        date_format:
          $ref: '#/components/schemas/Place.DateFormat'
        font_size:
          $ref: '#/components/schemas/Place.FontSize'
      required:
        - key
        - type
        - date_format
        - font_size
    Place.RecipientNamePlace:
      x-schema-role: model
      x-schema-direction: output
      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`.

        This place is read-only and does not require any action from the recipient.
      type: object
      properties:
        key:
          $ref: '#/components/schemas/Place.Key'
        type:
          allOf:
            - $ref: '#/components/schemas/Place.Type'
            - const: recipient_name
        recipient_key:
          $ref: '#/components/schemas/Place.RecipientKey'
        font_size:
          $ref: '#/components/schemas/Place.FontSize'
      required:
        - key
        - type
        - recipient_key
        - font_size
    Place.RecipientEmailPlace:
      x-schema-role: model
      x-schema-direction: output
      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`.

        This place is read-only and does not require any action from the recipient.
      type: object
      properties:
        key:
          $ref: '#/components/schemas/Place.Key'
        type:
          allOf:
            - $ref: '#/components/schemas/Place.Type'
            - const: recipient_email
        recipient_key:
          $ref: '#/components/schemas/Place.RecipientKey'
        font_size:
          $ref: '#/components/schemas/Place.FontSize'
      required:
        - key
        - type
        - recipient_key
        - font_size
    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
      examples:
        - Acme Corporation
    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'
      examples:
        - '#000000'
        - '#aa0000'
    Place.TextPlace:
      x-schema-role: model
      x-schema-direction: output
      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.

        Text places are useful for pre-filling information such as company names, reference numbers, or dates before the signing process begins.
      type: object
      properties:
        key:
          $ref: '#/components/schemas/Place.Key'
        type:
          allOf:
            - $ref: '#/components/schemas/Place.Type'
            - const: text
        value:
          $ref: '#/components/schemas/Place.TextValue'
        font_size:
          $ref: '#/components/schemas/Place.FontSize'
        font_color:
          $ref: '#/components/schemas/Place.FontColor'
      required:
        - key
        - type
        - value
        - font_size
        - font_color
    Place.Place:
      x-schema-role: model
      x-schema-direction: output
      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.

        Each place has a **type** that determines its behavior. The `type` field acts as a discriminator across the following place types:

        - **signature** -- A recipient draws or types their signature.
        - **initials** -- A recipient enters their initials.
        - **checkbox** -- A recipient checks or unchecks a box.
        - **text_input** -- A recipient types free-form text.
        - **boxed_text_input** -- A recipient enters text into individual character boxes.
        - **multiline_text_input** -- A recipient enters text across multiple lines.
        - **dropdown** -- A recipient selects from a list of options.
        - **radio_group** -- A recipient selects exactly one option from a set of scattered choices sharing a group.
        - **text** -- A read-only text value displayed on the document.
        - **envelope_completed_date** -- The date the envelope was completed.
        - **recipient_completed_date** -- The date the recipient completed their action.
        - **recipient_name** -- The recipient's name.
        - **recipient_email** -- The recipient's email address.

        ### Positioning

        Places can be positioned on a document in two ways:

        - **Placeholder text** -- Embed `[[place_key]]` in the document. The place appears where the placeholder is found.
        - **Fixed position** -- Specify exact coordinates using page number, top, and left values measured in points (1 point = 1/72 inch).
      oneOf:
        - $ref: '#/components/schemas/Place.SignaturePlace'
        - $ref: '#/components/schemas/Place.InitialsPlace'
        - $ref: '#/components/schemas/Place.RecipientDatePlace'
        - $ref: '#/components/schemas/Place.EnvelopeDatePlace'
        - $ref: '#/components/schemas/Place.RecipientNamePlace'
        - $ref: '#/components/schemas/Place.RecipientEmailPlace'
        - $ref: '#/components/schemas/Place.TextPlace'
        - $ref: '#/components/schemas/Place.TextInputPlace'
        - $ref: '#/components/schemas/Place.BoxedTextInputPlace'
        - $ref: '#/components/schemas/Place.MultiLineTextInputPlace'
        - $ref: '#/components/schemas/Place.DropdownPlace'
        - $ref: '#/components/schemas/Place.RadioGroupPlace'
        - $ref: '#/components/schemas/Place.CheckboxPlace'
      discriminator:
        propertyName: type
        mapping:
          signature: '#/components/schemas/Place.SignaturePlace'
          initials: '#/components/schemas/Place.InitialsPlace'
          checkbox: '#/components/schemas/Place.CheckboxPlace'
          text_input: '#/components/schemas/Place.TextInputPlace'
          boxed_text_input: '#/components/schemas/Place.BoxedTextInputPlace'
          multiline_text_input: '#/components/schemas/Place.MultiLineTextInputPlace'
          dropdown: '#/components/schemas/Place.DropdownPlace'
          radio_group: '#/components/schemas/Place.RadioGroupPlace'
          recipient_completed_date: '#/components/schemas/Place.RecipientDatePlace'
          envelope_completed_date: '#/components/schemas/Place.EnvelopeDatePlace'
          recipient_name: '#/components/schemas/Place.RecipientNamePlace'
          recipient_email: '#/components/schemas/Place.RecipientEmailPlace'
          text: '#/components/schemas/Place.TextPlace'
    Document.Places:
      x-schema-role: property
      x-schema-direction: output
      title: Places
      description: |
        The places attached to this document. Places are interactive fields or informational elements positioned on the document pages.

        Each 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.

        Places are positioned using either **placeholders** embedded in the document text or **fixed positions** specified in the `fixed_positions` array.
      type: array
      items:
        $ref: '#/components/schemas/Place.Place'
    Document.PageCount:
      x-schema-role: property
      x-schema-direction: output
      type: integer
      title: Document Page Count
      description: The total number of pages in the document after processing. For DOCX templates, this reflects the page count after template data has been merged.
      examples:
        - 3
    Document.DocxDocument:
      x-schema-role: model
      x-schema-direction: output
      title: Docx Document
      description: |
        A DOCX document within an envelope.

        DOCX 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.

        Provide template data in the `data` field when creating the envelope. SignatureAPI merges the template with your data to produce the final document.

        DOCX documents also support places and fixed positions, just like PDF documents.
      type: object
      properties:
        id:
          $ref: '#/components/schemas/Document.Id'
        key:
          $ref: '#/components/schemas/Document.Key'
        envelope_id:
          $ref: '#/components/schemas/Envelope.Id'
        title:
          $ref: '#/components/schemas/Document.Title'
        url:
          $ref: '#/components/schemas/Document.Url'
        format:
          allOf:
            - $ref: '#/components/schemas/Document.Format'
            - const: docx
        data:
          $ref: '#/components/schemas/Document.Data'
        fixed_positions:
          $ref: '#/components/schemas/Document.FixedPositions'
        places:
          $ref: '#/components/schemas/Document.Places'
        page_count:
          $ref: '#/components/schemas/Document.PageCount'
      required:
        - id
        - key
        - envelope_id
        - title
        - url
        - format
        - data
        - fixed_positions
        - places
        - page_count
    Document.PdfDocument:
      x-schema-role: model
      x-schema-direction: output
      title: Pdf Document
      description: |
        A PDF document within an envelope.

        PDF 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.
      type: object
      properties:
        id:
          $ref: '#/components/schemas/Document.Id'
        envelope_id:
          $ref: '#/components/schemas/Envelope.Id'
        key:
          $ref: '#/components/schemas/Document.Key'
        title:
          $ref: '#/components/schemas/Document.Title'
        url:
          $ref: '#/components/schemas/Document.Url'
        format:
          allOf:
            - $ref: '#/components/schemas/Document.Format'
            - const: pdf
        fixed_positions:
          $ref: '#/components/schemas/Document.FixedPositions'
        places:
          $ref: '#/components/schemas/Document.Places'
        page_count:
          $ref: '#/components/schemas/Document.PageCount'
      required:
        - id
        - key
        - envelope_id
        - title
        - url
        - format
        - fixed_positions
        - places
        - page_count
    Document.Document:
      x-schema-role: model
      x-schema-direction: output
      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.

        The `format` field determines the document type:

        - **`pdf`** -- A PDF file. Supports places positioned by placeholders or fixed coordinates.
        - **`docx`** -- A DOCX file. Supports template fields for dynamic content in addition to places.

        ### Document source

        Provide a publicly accessible URL when creating a document. You can host files yourself or use the **Upload** endpoint to upload files to SignatureAPI first.

        ### Places

        Each 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.

        Places are positioned in two ways:

        - **Placeholders** embedded in the document text (e.g., `[[place_key]]`).
        - **Fixed positions** specified by page number and coordinates in points.

        ### Relationships

        A document:

        - Belongs to one **envelope**.
        - Has zero or more **places**.
      oneOf:
        - $ref: '#/components/schemas/Document.DocxDocument'
        - $ref: '#/components/schemas/Document.PdfDocument'
      discriminator:
        propertyName: format
        mapping:
          docx: '#/components/schemas/Document.DocxDocument'
          pdf: '#/components/schemas/Document.PdfDocument'
    Envelope.Documents:
      x-schema-role: property
      x-schema-direction: output
      type: array
      title: Documents
      description: |-
        The documents included in the envelope for recipients to sign. An envelope can contain between 1 and 10 documents.

        Each 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.

        DOCX documents also support template data population through the `data` property.
      minItems: 1
      maxItems: 10
      items:
        $ref: '#/components/schemas/Document.Document'
    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.
      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.

        | Type | Description |
        |------|-------------|
        | `signer` | Signs documents. Every envelope must have at least one signing recipient. |
        | `qualified_signer` | Signs with a qualified electronic signature through a qualified trust service provider. |
        | `approver` | Reviews and approves documents without signing. |
        | `preparer` | Fills in document fields on behalf of another party. |
        | `automatic_signer` | The signature is applied automatically by the system. |
      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`.
      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.
      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.

        - `email_link` -- SignatureAPI sends the recipient an email with a direct link to the ceremony.
        - `email_code` -- SignatureAPI sends the recipient a 9-digit verification code by email. The ceremony URL is returned in the response for you to deliver.
        - `custom` -- Your application handles authentication and shares the ceremony URL directly.
        - `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.
      enum:
        - email_link
        - email_code
        - custom
        - identity_verification
    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.

        If not set, the envelope title is used as the subject line.
      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.

        If not set, the envelope message is used. Set to an empty string `""` to send the email with no message body.
      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.

        This is the default authentication method. If you create an envelope without specifying a ceremony, SignatureAPI uses email link authentication automatically.

        You 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.
      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 enters this code to authenticate and access the ceremony.

        Use this method to add an extra layer of verification to a ceremony.
      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.
      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.

        Include information that can verify how the recipient was authenticated, such as session IDs, timestamps, or user identifiers. Avoid including unnecessary sensitive details.
      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.

        Use 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.

        You 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.
      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.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.

        - `document_selfie` -- The recipient photographs a government-issued identity document and takes a selfie for a liveness and face match.
        - `eid` -- The recipient authenticates with a national or government-issued electronic identity scheme.
        - `video_ident` -- The recipient completes a video session with an agent who checks their identity document.
        - `reuse_credential` -- The recipient reuses an identity credential they already hold with the provider, without verifying again.
      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.
      example: document_selfie
      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`.

        - `stub` -- A built-in test provider that simulates the verification without contacting a real identity service.
      x-enum-descriptions:
        stub: Built-in test provider that simulates the verification.
      default: stub
      example: stub
      enum:
        - stub
    Ceremony.IdentityVerificationAuthentication:
      x-schema-role: model
      x-schema-direction: output
      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.

        Use this method when a signature needs a verified identity behind it, for example for qualified or advanced electronic signatures.

        Identity 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.

        You must provide a `method`. The `provider` is optional and defaults to `stub`.

        Identity verification is enabled per account. Contact support to turn it on before using it.
      type: object
      properties:
        type:
          allOf:
            - $ref: '#/components/schemas/Ceremony.AuthenticationType'
            - const: identity_verification
        method:
          $ref: '#/components/schemas/Ceremony.IdentityVerificationMethod'
        provider:
          $ref: '#/components/schemas/Ceremony.IdentityVerificationProvider'
      required:
        - type
    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.

        Four authentication types are available:

        - **email_link** -- SignatureAPI sends the recipient an email with a clickable link to the ceremony.
        - **email_code** -- SignatureAPI sends the recipient a 9-digit verification code by email.
        - **custom** -- Your application handles authentication and shares the ceremony URL directly.
        - **identity_verification** -- The recipient proves their identity with an identity verification provider.

        You can combine multiple types for added security. For example, use custom authentication first, then email code as a second step. See the constraints below:

        - `email_link` can only be the first step.
        - `custom` can only be the first step.
        - `email_link` and `custom` cannot be combined together.
        - `identity_verification` can never be the first step, and can appear at most once. It is enabled per account.
      type: array
      minItems: 1
      maxItems: 5
      items:
        oneOf:
          - $ref: '#/components/schemas/Ceremony.EmailLinkAuthentication'
          - $ref: '#/components/schemas/Ceremony.EmailCodeAuthentication'
          - $ref: '#/components/schemas/Ceremony.CustomAuthentication'
          - $ref: '#/components/schemas/Ceremony.IdentityVerificationAuthentication'
      discriminator:
        propertyName: type
        mapping:
          email_link: '#/components/schemas/Ceremony.EmailLinkAuthentication'
          email_code: '#/components/schemas/Ceremony.EmailCodeAuthentication'
          custom: '#/components/schemas/Ceremony.CustomAuthentication'
          identity_verification: '#/components/schemas/Ceremony.IdentityVerificationAuthentication'
    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.

        These values set the `frame-ancestors` directive in the ceremony's Content Security Policy (CSP) header.

        Each 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.

        If empty, the ceremony cannot be embedded in an iframe.

        Set to `['*']` to allow embedding from any origin. This is recommended only for development.
      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.

        SignatureAPI appends these query parameters to the URL:
        - `ceremony_result` -- The outcome: `ceremony.completed`, `ceremony.declined`, or `ceremony.failed`.
        - `envelope_id` -- The ID of the envelope.
        - `recipient_id` -- The ID of the recipient.

        For example: `https://example.com/?ceremony_result=ceremony.completed&envelope_id=...&recipient_id=...`

        If not set, the ceremony does not redirect.
      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).

        Set to `0` for an immediate redirect. Defaults to `3` seconds. Maximum is `20` seconds.
      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.

        - `standard` -- Full-length URL. Works for most use cases.
        - `short` -- Shortened URL. Useful for space-constrained channels like SMS or push notifications.

        Defaults to `standard`.
      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.

        This property is `null` when:
        - The ceremony uses `email_link` authentication, because SignatureAPI delivers the URL by email.
        - The ceremony is not active (for example, it has been completed, revoked, or declined).

        The URL expires after 30 days by default, or when a new ceremony is created for the same recipient.
      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.

        Each recipient can have one active ceremony at a time. When you create a new ceremony for a recipient, any previous ceremonies are automatically revoked.

        ### Lifecycle

        A ceremony moves through the following statuses:

        - **pending** -- The ceremony is created but the envelope is not yet active.
        - **active** -- The ceremony is ready for the recipient to access.
        - **completed** -- The recipient finished their actions.
        - **declined** -- The recipient declined to act.
        - **revoked** -- The ceremony was replaced by a new one or canceled.

        ### Authentication

        Every ceremony requires at least one authentication method. You can combine multiple methods that the recipient must complete in sequence before accessing the ceremony.
      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.

        Returns `null` if no ceremony has been created yet.
      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.

        **Deprecated**: Use the `ceremony` property on the recipient instead.
      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.

        | Type | Description |
        |------|-------------|
        | `email` | SignatureAPI emails the deliverable to the recipient. Default for signers. |
        | `none` | No deliverable email is sent. Your application is responsible for distributing the deliverable. Default for approvers and preparers. |
      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.

        | Option | Description |
        |--------|-------------|
        | `typed` | The signer types their signature. Their name is pre-filled. |
        | `drawn` | The signer draws their signature using a mouse, stylus, or touchscreen. |

        If not specified, both `typed` and `drawn` are available, with `typed` as the default.
      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.

        | Status | Description |
        |--------|-------------|
        | `pending` | The envelope has not been sent to the recipient yet. This is the initial status. |
        | `awaiting` | The recipient is waiting for previous recipients in the routing order to complete. |
        | `sent` | The invitation email has been sent to the recipient. |
        | `completed` | The recipient has completed their required actions (e.g., signed, approved). |
        | `rejected` | The recipient declined to complete the envelope. |
        | `soft_bounced` | The email was temporarily undeliverable (e.g., full mailbox). You can resend the request. |
        | `hard_bounced` | The email was permanently undeliverable (e.g., invalid address). Use the Replace endpoint to assign a new recipient. |
        | `failed` | An error occurred and the email could not be sent. |
        | `replaced` | The recipient was replaced with a new one via the Replace endpoint. |
      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.
    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.
    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.

        During 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.

        All signer actions are recorded in the audit log attached to the final deliverable.

        ### Delivery

        The `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.

        The signer receives an email with the ceremony link when the ceremony uses `email_link` authentication, which is the default.

        ### Signature options

        The `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.
      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.

        | Scheme | Description |
        |--------|-------------|
        | `eu_eidas` | European Union qualified electronic signature under eIDAS. |

        Additional schemes will be introduced in later releases.
      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.
        Present once the signature has been produced.
      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.

        The 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.

        Qualified 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.

        ### Delivery

        The `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.

        The qualified signer receives an email with the ceremony link when the ceremony uses `email_link` authentication, which is the default.

        ### Signature options

        The `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.
      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.

        Use 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.

        Approver actions are not recorded in the audit log.

        ### Delivery

        The `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.

        The 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.
      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.

        Use preparers when someone needs to populate document data before a signer receives the envelope — for example, a sales representative entering pricing or contract terms.

        The values a preparer enters are visible to subsequent recipients in the routing order. Preparer actions are not recorded in the audit log.

        ### Delivery

        The `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.

        The 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.
      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.
          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.
      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
        of this person. This string will be shown as-is in the audit log.
      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.
      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.

        Each recipient has a **type** that determines what they can do:

        - **Signer** — signs documents. This is the most common recipient type. Every envelope must have at least one signing recipient.
        - **Approver** — reviews and approves documents without signing them.
        - **Preparer** — fills in document fields before the signer receives them.
        - **Automatic Signer** — the signature is applied automatically by the system.

        The `type` field acts as a discriminator. The properties available on a recipient depend on its type.

        ### Routing

        Recipients 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.

        ### Lifecycle

        A 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.
      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'
    Envelope.Recipients:
      x-schema-role: property
      x-schema-direction: output
      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.

        Four recipient types are supported:

        - **signer** -- Signs the documents.
        - **preparer** -- Fills in fields before signers receive the documents.
        - **approver** -- Reviews and approves the documents without signing.
        - **automatic_signer** -- Has their signature applied automatically.

        The 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: '#/components/schemas/Recipient.Recipient'
    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.

        If not specified, the account's default sender name is used.
      minLength: 1
      maxLength: 500
      examples:
        - Melon Musk
    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.

        If not specified, the account's default sender email is used.
      maxLength: 320
      examples:
        - melon@example.com
    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.
      minLength: 1
      maxLength: 500
      default: null
      examples:
        - SpiceX
    Envelope.Sender:
      x-schema-role: property
      x-schema-direction: output
      type: object
      title: Envelope Sender
      description: |-
        The sender of the envelope. Sender information appears in the emails sent to recipients, identifying who initiated the signing request.

        If omitted, the account's default sender name and email will be used.
      properties:
        name:
          $ref: '#/components/schemas/Envelope.SenderName'
        email:
          $ref: '#/components/schemas/Envelope.SenderEmail'
        organization:
          $ref: '#/components/schemas/Envelope.SenderOrganization'
      required:
        - name
        - email
        - organization
    Envelope.Captures:
      x-schema-role: property
      x-schema-direction: output
      type: object
      title: Envelope Captures
      description: |
        Data captured from recipients during the signing ceremony. Each key corresponds to a `capture_as` identifier defined on a text input or checkbox place in the document. Values are strings for text inputs, booleans for checkboxes, or null if not yet filled.
      additionalProperties:
        anyOf:
          - type: string
          - type: boolean
          - type: 'null'
      propertyNames:
        type: string
        pattern: ^[a-z][a-z0-9_]*$
        minLength: 1
        maxLength: 32
      unevaluatedProperties: false
    Envelope.SnapshotUrl:
      x-schema-role: property
      x-schema-direction: output
      type:
        - string
        - 'null'
      title: Envelope Snapshot URL
      description: |
        The URL to a PDF snapshot of the envelope, showing documents and signatures collected so far.

        ## Availability

        To return a valid URL, the envelope must meet all of the following criteria (otherwise, this field returns null):

        - It uses sequential routing.
        - It is currently in progress (ie. not `completed`).
        - It was created within 1 year.

        ## Pre-signed URLs (Default)

        By default, this is a short-lived, pre-signed URL that requires no further authentication to download.

        The URL expires after 1 hour. If the link has expired, you can generate a new one by retrieving the envelope again.

        ## Authenticated URLs

        If you requested authenticated URLs, for example to achieve HIPAA compliance, the URL must be accessed using the API key, in the same way as other requests to this API.

        Authenticated URLs do not expire.
      format: uri
      examples:
        - https://www.example.com/repository/envelope-snapshot.pdf
    Deliverable.Id:
      x-schema-role: property
      x-schema-direction: output
      type: string
      title: Deliverable Id
      description: The unique identifier of the deliverable.
      examples:
        - del_LXRDwyTeJDVrWXmjwxsAGPq
    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.

        Must 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
      examples:
        - hr_pack
        - compliance_acceptance
    Deliverable.EnvelopeId:
      x-schema-role: property
      x-schema-direction: output
      allOf:
        - title: Envelope ID
          description: The unique identifier of the envelope that this deliverable belongs to.
        - $ref: '#/components/schemas/Envelope.Id'
    Deliverable.Type:
      x-schema-role: property
      x-schema-direction: any
      type: string
      title: Deliverable Type
      enum:
        - simple
        - standard
      description: |
        The type of the deliverable.

        - `standard` -- Includes signed documents and an audit log with a certificate of completion.
        - `simple` -- Includes signed documents only, without an audit log.
      examples:
        - standard
    Deliverable.Status:
      x-schema-role: property
      x-schema-direction: output
      type: string
      title: Deliverable Status
      description: |
        The current status of the deliverable.

        - **`pending`**: The deliverable is pending generation. This occurs while the envelope is not yet completed.
        - **`processing`**: The envelope is completed and the deliverable is being generated. This usually takes a few seconds.
        - **`generated`**: The deliverable has been generated. The deliverable object includes a URL where the deliverable can be downloaded. This is the final status of the deliverable.
        - **`failed`**: The deliverable has failed to be generated. This is a rare event and support is notified automatically.
      enum:
        - pending
        - processing
        - generated
        - failed
      examples:
        - generated
    Deliverable.Url:
      x-schema-role: property
      x-schema-direction: output
      type:
        - string
        - 'null'
      title: Deliverable Url
      format: uri
      description: |
        The URL to download the deliverable once it has been generated. If the deliverable has not yet been generated, this will be `null`.

        ## Pre-signed URLs (Default)

        By default, this is a short-lived, pre-signed URL that requires no further authentication to download.

        The URL expires after 1 hour. If the link has expired, you can generate a new one by retrieving the deliverable again.

        ## Authenticated URLs

        If you requested authenticated URLs, for example to achieve HIPAA compliance, the URL must be accessed using the API key, in the same way as other requests to this API.

        Authenticated URLs do not expire.
      examples:
        - https://www.example.com/repository/audit-log.pdf
    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.

            If not specified, the timezone of the envelope is used.
        - $ref: '#/components/schemas/Envelope.Timezone'
    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.

            If not specified, the timestamp format of the envelope is used.
        - $ref: '#/components/schemas/Envelope.TimestampFormat'
    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.

            If not specified, the language of the envelope is used.
        - $ref: '#/components/schemas/Envelope.Language'
    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.

        By 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.
      examples:
        - - contract
          - addendum
      items:
        $ref: '#/components/schemas/Document.Key'
      minItems: 1
      maxItems: 10
    Deliverable.MaskedPassword:
      x-schema-role: property
      x-schema-direction: output
      title: Deliverable Password
      description: |
        A password used to encrypt the deliverable PDF with AES-128 encryption. Recipients must enter this password to open the file.

        The 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.

        For strong protection, use at least 12 characters with a random mix of uppercase, lowercase, and numbers.

        In API responses, the password is masked as `********`.

        To use this feature, contact support to enable it on your account.
      oneOf:
        - type: string
          const: '********'
        - type: 'null'
    Deliverable.CreatedAt:
      x-schema-role: property
      x-schema-direction: output
      type: string
      format: date-time
      title: Deliverable Created At
      description: Time at which the deliverable was created. This is set when the envelope is created or when a deliverable is created via the API.
      examples:
        - '2024-01-01T00:00:00Z'
    Deliverable.GeneratedAt:
      x-schema-role: property
      x-schema-direction: output
      type:
        - string
        - 'null'
      format: date-time
      title: Deliverable Generated At
      description: Time at which the deliverable was successfully generated. This is `null` until the deliverable reaches `generated` status.
      examples:
        - '2024-01-01T00:01:00Z'
    Deliverable.Standard:
      x-schema-role: model
      x-schema-direction: output
      type: object
      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.

        The `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.

        If not specified, these values default to the envelope's settings.

        You can customize which documents are included using the `included_documents` field. Password protection is also available.
      properties:
        id:
          $ref: '#/components/schemas/Deliverable.Id'
        name:
          $ref: '#/components/schemas/Deliverable.Name'
        envelope_id:
          $ref: '#/components/schemas/Deliverable.EnvelopeId'
        type:
          allOf:
            - $ref: '#/components/schemas/Deliverable.Type'
            - const: standard
        status:
          $ref: '#/components/schemas/Deliverable.Status'
        url:
          $ref: '#/components/schemas/Deliverable.Url'
        timezone:
          $ref: '#/components/schemas/Deliverable.Timezone'
        timestamp_format:
          $ref: '#/components/schemas/Deliverable.TimestampFormat'
        language:
          $ref: '#/components/schemas/Deliverable.Language'
        included_documents:
          $ref: '#/components/schemas/Deliverable.IncludedDocuments'
        password:
          $ref: '#/components/schemas/Deliverable.MaskedPassword'
        created_at:
          $ref: '#/components/schemas/Deliverable.CreatedAt'
        generated_at:
          $ref: '#/components/schemas/Deliverable.GeneratedAt'
      required:
        - id
        - name
        - envelope_id
        - type
        - status
        - url
        - timezone
        - timestamp_format
        - language
        - included_documents
        - password
        - created_at
        - generated_at
    Deliverable.Simple:
      x-schema-role: model
      x-schema-direction: output
      type: object
      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.

        The 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.

        You can customize which documents are included using the `included_documents` field. Password protection is also available.
      properties:
        id:
          $ref: '#/components/schemas/Deliverable.Id'
        name:
          $ref: '#/components/schemas/Deliverable.Name'
        envelope_id:
          $ref: '#/components/schemas/Deliverable.EnvelopeId'
        type:
          allOf:
            - $ref: '#/components/schemas/Deliverable.Type'
            - const: simple
        status:
          $ref: '#/components/schemas/Deliverable.Status'
        url:
          $ref: '#/components/schemas/Deliverable.Url'
        included_documents:
          $ref: '#/components/schemas/Deliverable.IncludedDocuments'
        password:
          $ref: '#/components/schemas/Deliverable.MaskedPassword'
        created_at:
          $ref: '#/components/schemas/Deliverable.CreatedAt'
        generated_at:
          $ref: '#/components/schemas/Deliverable.GeneratedAt'
      required:
        - id
        - name
        - envelope_id
        - type
        - status
        - url
        - included_documents
        - password
        - created_at
        - generated_at
    Deliverable.Deliverable:
      x-schema-role: model
      x-schema-direction: output
      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.

        The `type` field determines the deliverable variant:

        - `standard` -- Includes signed documents and an audit log with a certificate of completion.
        - `simple` -- Includes signed documents only, without an audit log.

        ### Lifecycle

        A deliverable moves through these statuses:

        1. `pending` -- Waiting for the envelope to complete.
        2. `processing` -- The envelope is completed and the deliverable is being generated. This usually takes a few seconds.
        3. `generated` -- The deliverable is ready. The `url` field contains a download link.
        4. `failed` -- Generation failed. This is rare and triggers an automatic alert to support.

        ### Default behavior

        When 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.
      oneOf:
        - $ref: '#/components/schemas/Deliverable.Standard'
        - $ref: '#/components/schemas/Deliverable.Simple'
        - type: 'null'
      discriminator:
        propertyName: type
        mapping:
          standard: '#/components/schemas/Deliverable.Standard'
          simple: '#/components/schemas/Deliverable.Simple'
    Envelope.CreatedAt:
      x-schema-role: property
      x-schema-direction: output
      type: string
      format: date-time
      title: Envelope Created At
      description: The time at which the envelope was created, in ISO 8601 format.
      examples:
        - '2024-06-15T10:00:00Z'
    Envelope.CompletedAt:
      x-schema-role: property
      x-schema-direction: output
      type:
        - string
        - 'null'
      format: date-time
      title: Envelope Completed At
      description: |
        The time at which all recipients completed the envelope, in ISO 8601 format.

        This field is `null` until the envelope reaches `completed` status.
      examples:
        - '2024-06-15T14:30:00Z'
    Envelope.Envelope:
      x-schema-role: model
      x-schema-direction: output
      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.

        ### Lifecycle

        An envelope moves through five statuses:

        1. `processing` -- The envelope is being prepared. Documents are validated and recipients are notified.
        2. `in_progress` -- The envelope has been sent to recipients and is waiting for all participants to complete their part.
        3. `completed` -- All recipients have completed their part (for example, signed). A **deliverable** is generated and sent to the recipients.
        4. `failed` -- An internal error occurred during processing. This is rare and triggers an automatic alert.
        5. `canceled` -- The signing process was intentionally stopped before completion via the Cancel Envelope endpoint.

        ### Relationships

        An envelope:

        - Has one or more **recipients** (signers, preparers, or approvers).
        - Has one or more **documents** (PDF or DOCX format).
        - Has one or more **deliverables** generated upon completion.
      type: object
      properties:
        id:
          $ref: '#/components/schemas/Envelope.Id'
        status:
          $ref: '#/components/schemas/Envelope.Status'
        label:
          $ref: '#/components/schemas/Envelope.Label'
        metadata:
          $ref: '#/components/schemas/Envelope.Metadata'
        message:
          $ref: '#/components/schemas/Envelope.Message'
        mode:
          $ref: '#/components/schemas/Envelope.Mode'
        title:
          $ref: '#/components/schemas/Envelope.Title'
        topics:
          $ref: '#/components/schemas/Envelope.Topics'
        branding:
          $ref: '#/components/schemas/Envelope.Branding'
        timezone:
          $ref: '#/components/schemas/Envelope.Timezone'
        timestamp_format:
          $ref: '#/components/schemas/Envelope.TimestampFormat'
        language:
          $ref: '#/components/schemas/Envelope.Language'
        routing:
          $ref: '#/components/schemas/Envelope.Routing'
        attestation:
          $ref: '#/components/schemas/Envelope.Attestation'
        documents:
          $ref: '#/components/schemas/Envelope.Documents'
        recipients:
          $ref: '#/components/schemas/Envelope.Recipients'
        sender:
          $ref: '#/components/schemas/Envelope.Sender'
        captures:
          $ref: '#/components/schemas/Envelope.Captures'
        snapshot_url:
          $ref: '#/components/schemas/Envelope.SnapshotUrl'
        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`.

            Two types are available:

            - `standard` -- Includes signed documents and an audit log.
            - `simple` -- Includes signed documents only, without an audit log.

            If no deliverable is provided, a `standard` deliverable is automatically generated.
          allOf:
            - $ref: '#/components/schemas/Deliverable.Deliverable'
        created_at:
          $ref: '#/components/schemas/Envelope.CreatedAt'
        completed_at:
          $ref: '#/components/schemas/Envelope.CompletedAt'
      required:
        - id
        - label
        - metadata
        - message
        - status
        - mode
        - title
        - topics
        - timezone
        - timestamp_format
        - language
        - routing
        - attestation
        - documents
        - recipients
        - sender
        - captures
        - snapshot_url
        - deliverable
        - created_at
        - completed_at
    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.
      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
    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.

        The following branding options are available:

        - **logo** -- A logo image displayed in the header of emails and the signing ceremony. Must be a PNG file uploaded to the Library.
        - **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`.
        - **email.footer** -- A custom footer appended to emails. Supports Markdown for bold, italic, and paragraph breaks. Useful for disclaimers or contact information.
        - **email.logo_position** -- Controls logo alignment in emails: `left`, `center`, or `right`. Defaults to `left`.
        - **email.from** -- The email address shown in the "From" field. Defaults to `noreply@signatureapi.com`. Custom domains require DNS configuration.
      properties:
        logo:
          $ref: '#/components/schemas/Envelope.BrandingLogo'
        accent_color:
          $ref: '#/components/schemas/Envelope.BrandingAccentColor'
        email:
          type: object
          additionalProperties: false
          properties:
            from:
              $ref: '#/components/schemas/Envelope.BrandingEmailFrom'
            footer:
              $ref: '#/components/schemas/Envelope.BrandingEmailFooter'
            logo_position:
              $ref: '#/components/schemas/Envelope.BrandingEmailLogoPosition'
    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.

        The 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.

        For strong protection, use at least 12 characters with a random mix of uppercase, lowercase, and numbers.

        In API responses, the password is masked as `********`.

        To use this feature, contact support to enable it on your account.
    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.

        The `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.

        If not specified, these values default to the envelope's settings.

        You can customize which documents are included using the `included_documents` field. Password protection is also available.
      type: object
      additionalProperties: false
      properties:
        name:
          $ref: '#/components/schemas/Deliverable.Name'
        type:
          allOf:
            - $ref: '#/components/schemas/Deliverable.Type'
            - const: standard
        timezone:
          $ref: '#/components/schemas/Deliverable.Timezone'
        timestamp_format:
          $ref: '#/components/schemas/Deliverable.TimestampFormat'
        language:
          $ref: '#/components/schemas/Deliverable.Language'
        included_documents:
          $ref: '#/components/schemas/Deliverable.IncludedDocuments'
        password:
          $ref: '#/components/schemas/Deliverable.Password'
      required:
        - type
    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.

        The 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.

        You can customize which documents are included using the `included_documents` field. Password protection is also available.
      type: object
      additionalProperties: false
      properties:
        name:
          $ref: '#/components/schemas/Deliverable.Name'
        type:
          allOf:
            - $ref: '#/components/schemas/Deliverable.Type'
            - const: simple
        included_documents:
          $ref: '#/components/schemas/Deliverable.IncludedDocuments'
        password:
          $ref: '#/components/schemas/Deliverable.Password'
      required:
        - type
    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.

        The `type` field determines the deliverable variant:

        - `standard` -- Includes signed documents and an audit log with a certificate of completion.
        - `simple` -- Includes signed documents only, without an audit log.

        ### Lifecycle

        A deliverable moves through these statuses:

        1. `pending` -- Waiting for the envelope to complete.
        2. `processing` -- The envelope is completed and the deliverable is being generated. This usually takes a few seconds.
        3. `generated` -- The deliverable is ready. The `url` field contains a download link.
        4. `failed` -- Generation failed. This is rare and triggers an automatic alert to support.

        ### Default behavior

        When 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.
      oneOf:
        - $ref: '#/components/schemas/Deliverable.StandardInput'
        - $ref: '#/components/schemas/Deliverable.SimpleInput'
        - type: 'null'
      discriminator:
        propertyName: type
        mapping:
          standard: '#/components/schemas/Deliverable.StandardInput'
          simple: '#/components/schemas/Deliverable.SimpleInput'
    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.

        Each 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.

        The width is automatically calculated using a 5:2 ratio based on the height.
      type: object
      additionalProperties: false
      properties:
        key:
          $ref: '#/components/schemas/Place.Key'
        type:
          allOf:
            - $ref: '#/components/schemas/Place.Type'
            - const: signature
        recipient_key:
          $ref: '#/components/schemas/Place.RecipientKey'
        height:
          $ref: '#/components/schemas/Place.SignatureHeight'
      required:
        - key
        - type
        - recipient_key
    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.

        Each 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.

        The width equals the height.
      type: object
      additionalProperties: false
      properties:
        key:
          $ref: '#/components/schemas/Place.Key'
        type:
          allOf:
            - $ref: '#/components/schemas/Place.Type'
            - const: initials
        recipient_key:
          $ref: '#/components/schemas/Place.RecipientKey'
        height:
          $ref: '#/components/schemas/Place.InitialsHeight'
      required:
        - key
        - type
        - recipient_key
    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.

        Checkbox 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.

        Use `capture_as` to store the checkbox value in the envelope's captures for later retrieval.
      type: object
      additionalProperties: false
      properties:
        key:
          $ref: '#/components/schemas/Place.Key'
        type:
          allOf:
            - $ref: '#/components/schemas/Place.Type'
            - const: checkbox
        requirement:
          allOf:
            - $ref: '#/components/schemas/Place.Requirement'
            - default: optional
        recipient_key:
          $ref: '#/components/schemas/Place.RecipientKey'
        symbol:
          $ref: '#/components/schemas/Place.CheckboxSymbol'
        height:
          $ref: '#/components/schemas/Place.CheckboxHeight'
        capture_as:
          $ref: '#/components/schemas/Place.CaptureAs'
      required:
        - key
        - type
        - recipient_key
    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.

        Text 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.

        Input 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.

        Use `capture_as` to store the entered text in the envelope's captures for later retrieval.
      type: object
      additionalProperties: false
      properties:
        key:
          $ref: '#/components/schemas/Place.Key'
        type:
          allOf:
            - $ref: '#/components/schemas/Place.Type'
            - const: text_input
        recipient_key:
          $ref: '#/components/schemas/Place.RecipientKey'
        requirement:
          allOf:
            - $ref: '#/components/schemas/Place.Requirement'
            - default: required
        prompt:
          $ref: '#/components/schemas/Place.Prompt'
        hint:
          $ref: '#/components/schemas/Place.Hint'
        capture_as:
          $ref: '#/components/schemas/Place.CaptureAs'
        format:
          $ref: '#/components/schemas/Place.TextInputFormat'
        format_message:
          $ref: '#/components/schemas/Place.TextInputFormatMessage'
        font_size:
          $ref: '#/components/schemas/Place.TextInputFontSize'
        width:
          $ref: '#/components/schemas/Place.TextInputWidth'
      required:
        - key
        - type
        - recipient_key
    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.

        Boxed text input places are available in envelopes with sequential signing. The `box_count` property controls how many character boxes are displayed.

        Use `capture_as` to store the entered text in the envelope's captures for later retrieval.
      type: object
      additionalProperties: false
      properties:
        key:
          $ref: '#/components/schemas/Place.Key'
        type:
          allOf:
            - $ref: '#/components/schemas/Place.Type'
            - const: boxed_text_input
        recipient_key:
          $ref: '#/components/schemas/Place.RecipientKey'
        requirement:
          allOf:
            - $ref: '#/components/schemas/Place.Requirement'
            - default: required
        font_size:
          $ref: '#/components/schemas/Place.TextInputFontSize'
        height:
          $ref: '#/components/schemas/Place.TextInputHeight'
        width:
          $ref: '#/components/schemas/Place.TextInputWidth'
        box_count:
          $ref: '#/components/schemas/Place.BoxCount'
        prompt:
          $ref: '#/components/schemas/Place.Prompt'
        hint:
          $ref: '#/components/schemas/Place.Hint'
        capture_as:
          $ref: '#/components/schemas/Place.CaptureAs'
      required:
        - key
        - type
        - recipient_key
        - font_size
        - width
        - height
    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.

        Multi-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`.

        Use `capture_as` to store the entered text in the envelope's captures for later retrieval.
      type: object
      additionalProperties: false
      properties:
        key:
          $ref: '#/components/schemas/Place.Key'
        type:
          allOf:
            - $ref: '#/components/schemas/Place.Type'
            - const: multiline_text_input
        recipient_key:
          $ref: '#/components/schemas/Place.RecipientKey'
        requirement:
          allOf:
            - $ref: '#/components/schemas/Place.Requirement'
            - default: required
        prompt:
          $ref: '#/components/schemas/Place.Prompt'
        hint:
          $ref: '#/components/schemas/Place.Hint'
        capture_as:
          $ref: '#/components/schemas/Place.CaptureAs'
        font_size:
          $ref: '#/components/schemas/Place.TextInputFontSize'
        width:
          $ref: '#/components/schemas/Place.TextInputWidth'
        line_count:
          $ref: '#/components/schemas/Place.MultiLineTextInputLineCount'
        line_height:
          $ref: '#/components/schemas/Place.MultiLineTextInputLineHeight'
      required:
        - key
        - type
        - recipient_key
        - width
        - line_count
    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.

        Dropdown 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`.

        The `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.

        Use `capture_as` to store the selected value in the envelope's captures for later retrieval.
      type: object
      additionalProperties: false
      properties:
        key:
          $ref: '#/components/schemas/Place.Key'
        type:
          allOf:
            - $ref: '#/components/schemas/Place.Type'
            - const: dropdown
        recipient_key:
          $ref: '#/components/schemas/Place.RecipientKey'
        requirement:
          allOf:
            - $ref: '#/components/schemas/Place.Requirement'
            - default: required
        prompt:
          $ref: '#/components/schemas/Place.Prompt'
        hint:
          $ref: '#/components/schemas/Place.Hint'
        capture_as:
          $ref: '#/components/schemas/Place.CaptureAs'
        options:
          $ref: '#/components/schemas/Place.DropdownPlaceOptions'
        default:
          $ref: '#/components/schemas/Place.DropdownPlaceDefault'
        behavior:
          $ref: '#/components/schemas/Place.DropdownPlaceBehavior'
        font_size:
          $ref: '#/components/schemas/Place.TextInputFontSize'
        width:
          $ref: '#/components/schemas/Place.TextInputWidth'
      required:
        - key
        - type
        - recipient_key
        - options
    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.

        Unlike 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.

        ### Options

        The `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.

        Provide `default` to preselect an option; its value must match one of the option `value`s.

        ### Positioning

        Options 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`.

        For 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`.

        Radio group places are available in envelopes with sequential signing.
      type: object
      additionalProperties: false
      properties:
        key:
          $ref: '#/components/schemas/Place.Key'
        type:
          allOf:
            - $ref: '#/components/schemas/Place.Type'
            - const: radio_group
        recipient_key:
          $ref: '#/components/schemas/Place.RecipientKey'
        options:
          $ref: '#/components/schemas/Place.RadioGroupPlaceOptions'
        symbol:
          $ref: '#/components/schemas/Place.RadioGroupSymbol'
        shape:
          $ref: '#/components/schemas/Place.RadioGroupShape'
        requirement:
          allOf:
            - $ref: '#/components/schemas/Place.Requirement'
            - default: required
        default:
          $ref: '#/components/schemas/Place.RadioGroupPlaceDefault'
        capture_as:
          $ref: '#/components/schemas/Place.CaptureAs'
        height:
          $ref: '#/components/schemas/Place.RadioGroupHeight'
      required:
        - key
        - type
        - recipient_key
        - options
    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.

        Each 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.
      type: object
      additionalProperties: false
      properties:
        key:
          $ref: '#/components/schemas/Place.Key'
        type:
          allOf:
            - $ref: '#/components/schemas/Place.Type'
            - const: recipient_completed_date
        recipient_key:
          $ref: '#/components/schemas/Place.RecipientKey'
        date_format:
          $ref: '#/components/schemas/Place.DateFormat'
        font_size:
          $ref: '#/components/schemas/Place.FontSize'
      required:
        - key
        - type
        - recipient_key
    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.

        This 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.
      type: object
      additionalProperties: false
      properties:
        key:
          $ref: '#/components/schemas/Place.Key'
        type:
          allOf:
            - $ref: '#/components/schemas/Place.Type'
            - const: envelope_completed_date
        date_format:
          $ref: '#/components/schemas/Place.DateFormat'
        font_size:
          $ref: '#/components/schemas/Place.FontSize'
      required:
        - key
        - type
    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`.

        This place is read-only and does not require any action from the recipient.
      type: object
      additionalProperties: false
      properties:
        key:
          $ref: '#/components/schemas/Place.Key'
        type:
          allOf:
            - $ref: '#/components/schemas/Place.Type'
            - const: recipient_name
        recipient_key:
          $ref: '#/components/schemas/Place.RecipientKey'
        font_size:
          $ref: '#/components/schemas/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`.

        This place is read-only and does not require any action from the recipient.
      type: object
      additionalProperties: false
      properties:
        key:
          $ref: '#/components/schemas/Place.Key'
        type:
          allOf:
            - $ref: '#/components/schemas/Place.Type'
            - const: recipient_email
        recipient_key:
          $ref: '#/components/schemas/Place.RecipientKey'
        font_size:
          $ref: '#/components/schemas/Place.FontSize'
      required:
        - key
        - type
        - recipient_key
    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.

        Text places are useful for pre-filling information such as company names, reference numbers, or dates before the signing process begins.
      type: object
      additionalProperties: false
      properties:
        key:
          $ref: '#/components/schemas/Place.Key'
        type:
          allOf:
            - $ref: '#/components/schemas/Place.Type'
            - const: text
        value:
          $ref: '#/components/schemas/Place.TextValue'
        font_size:
          $ref: '#/components/schemas/Place.FontSize'
        font_color:
          $ref: '#/components/schemas/Place.FontColor'
      required:
        - key
        - type
        - value
    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.

        Each place has a **type** that determines its behavior. The `type` field acts as a discriminator across the following place types:

        - **signature** -- A recipient draws or types their signature.
        - **initials** -- A recipient enters their initials.
        - **checkbox** -- A recipient checks or unchecks a box.
        - **text_input** -- A recipient types free-form text.
        - **boxed_text_input** -- A recipient enters text into individual character boxes.
        - **multiline_text_input** -- A recipient enters text across multiple lines.
        - **dropdown** -- A recipient selects from a list of options.
        - **radio_group** -- A recipient selects exactly one option from a set of scattered choices sharing a group.
        - **text** -- A read-only text value displayed on the document.
        - **envelope_completed_date** -- The date the envelope was completed.
        - **recipient_completed_date** -- The date the recipient completed their action.
        - **recipient_name** -- The recipient's name.
        - **recipient_email** -- The recipient's email address.

        ### Positioning

        Places can be positioned on a document in two ways:

        - **Placeholder text** -- Embed `[[place_key]]` in the document. The place appears where the placeholder is found.
        - **Fixed position** -- Specify exact coordinates using page number, top, and left values measured in points (1 point = 1/72 inch).
      oneOf:
        - $ref: '#/components/schemas/Place.SignaturePlaceInput'
        - $ref: '#/components/schemas/Place.InitialsPlaceInput'
        - $ref: '#/components/schemas/Place.RecipientDatePlaceInput'
        - $ref: '#/components/schemas/Place.EnvelopeDatePlaceInput'
        - $ref: '#/components/schemas/Place.RecipientNamePlaceInput'
        - $ref: '#/components/schemas/Place.RecipientEmailPlaceInput'
        - $ref: '#/components/schemas/Place.TextPlaceInput'
        - $ref: '#/components/schemas/Place.TextInputPlaceInput'
        - $ref: '#/components/schemas/Place.BoxedTextInputPlaceInput'
        - $ref: '#/components/schemas/Place.MultiLineTextInputPlaceInput'
        - $ref: '#/components/schemas/Place.DropdownPlaceInput'
        - $ref: '#/components/schemas/Place.RadioGroupPlaceInput'
        - $ref: '#/components/schemas/Place.CheckboxPlaceInput'
      discriminator:
        propertyName: type
        mapping:
          signature: '#/components/schemas/Place.SignaturePlaceInput'
          initials: '#/components/schemas/Place.InitialsPlaceInput'
          checkbox: '#/components/schemas/Place.CheckboxPlaceInput'
          text_input: '#/components/schemas/Place.TextInputPlaceInput'
          boxed_text_input: '#/components/schemas/Place.BoxedTextInputPlaceInput'
          multiline_text_input: '#/components/schemas/Place.MultiLineTextInputPlaceInput'
          dropdown: '#/components/schemas/Place.DropdownPlaceInput'
          radio_group: '#/components/schemas/Place.RadioGroupPlaceInput'
          recipient_completed_date: '#/components/schemas/Place.RecipientDatePlaceInput'
          envelope_completed_date: '#/components/schemas/Place.EnvelopeDatePlaceInput'
          recipient_name: '#/components/schemas/Place.RecipientNamePlaceInput'
          recipient_email: '#/components/schemas/Place.RecipientEmailPlaceInput'
          text: '#/components/schemas/Place.TextPlaceInput'
    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.

        Each 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.

        Places are positioned using either **placeholders** embedded in the document text or **fixed positions** specified in the `fixed_positions` array.
      type: array
      items:
        $ref: '#/components/schemas/Place.PlaceInput'
      default: []
    Document.DocxDocumentInput:
      x-schema-role: model
      x-schema-direction: input
      title: Docx Document
      description: |
        A DOCX document within an envelope.

        DOCX 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.

        Provide template data in the `data` field when creating the envelope. SignatureAPI merges the template with your data to produce the final document.

        DOCX documents also support places and fixed positions, just like PDF documents.
      type: object
      additionalProperties: false
      properties:
        key:
          $ref: '#/components/schemas/Document.Key'
        title:
          $ref: '#/components/schemas/Document.Title'
        url:
          $ref: '#/components/schemas/Document.Url'
        format:
          allOf:
            - $ref: '#/components/schemas/Document.Format'
            - const: docx
        data:
          $ref: '#/components/schemas/Document.Data'
        fixed_positions:
          $ref: '#/components/schemas/Document.FixedPositions'
        places:
          $ref: '#/components/schemas/Document.PlacesInput'
      required:
        - url
        - format
    Document.PdfDocumentInput:
      x-schema-role: model
      x-schema-direction: input
      title: Pdf Document
      description: |
        A PDF document within an envelope.

        PDF 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.
      type: object
      additionalProperties: false
      properties:
        key:
          $ref: '#/components/schemas/Document.Key'
        title:
          $ref: '#/components/schemas/Document.Title'
        url:
          $ref: '#/components/schemas/Document.Url'
        format:
          allOf:
            - $ref: '#/components/schemas/Document.Format'
            - const: pdf
        fixed_positions:
          $ref: '#/components/schemas/Document.FixedPositions'
        places:
          $ref: '#/components/schemas/Document.PlacesInput'
      required:
        - url
        - format
    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.

        The `format` field determines the document type:

        - **`pdf`** -- A PDF file. Supports places positioned by placeholders or fixed coordinates.
        - **`docx`** -- A DOCX file. Supports template fields for dynamic content in addition to places.

        ### Document source

        Provide a publicly accessible URL when creating a document. You can host files yourself or use the **Upload** endpoint to upload files to SignatureAPI first.

        ### Places

        Each 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.

        Places are positioned in two ways:

        - **Placeholders** embedded in the document text (e.g., `[[place_key]]`).
        - **Fixed positions** specified by page number and coordinates in points.

        ### Relationships

        A document:

        - Belongs to one **envelope**.
        - Has zero or more **places**.
      oneOf:
        - $ref: '#/components/schemas/Document.DocxDocumentInput'
        - $ref: '#/components/schemas/Document.PdfDocumentInput'
      discriminator:
        propertyName: format
        mapping:
          docx: '#/components/schemas/Document.DocxDocumentInput'
          pdf: '#/components/schemas/Document.PdfDocumentInput'
    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.

        Each 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.

        DOCX documents also support template data population through the `data` property.
      minItems: 1
      maxItems: 10
      items:
        $ref: '#/components/schemas/Document.DocumentInput'
    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.

        This is the default authentication method. If you create an envelope without specifying a ceremony, SignatureAPI uses email link authentication automatically.

        You 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.
      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 enters this code to authenticate and access the ceremony.

        Use this method to add an extra layer of verification to a ceremony.
      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.

        Use 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.

        You 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.
      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.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.

        Use this method when a signature needs a verified identity behind it, for example for qualified or advanced electronic signatures.

        Identity 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.

        You must provide a `method`. The `provider` is optional and defaults to `stub`.

        Identity verification is enabled per account. Contact support to turn it on before using it.
      type: object
      additionalProperties: false
      properties:
        type:
          allOf:
            - $ref: '#/components/schemas/Ceremony.AuthenticationType'
            - const: identity_verification
        method:
          $ref: '#/components/schemas/Ceremony.IdentityVerificationMethod'
        provider:
          $ref: '#/components/schemas/Ceremony.IdentityVerificationProvider'
      required:
        - type
        - method
    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.

        Four authentication types are available:

        - **email_link** -- SignatureAPI sends the recipient an email with a clickable link to the ceremony.
        - **email_code** -- SignatureAPI sends the recipient a 9-digit verification code by email.
        - **custom** -- Your application handles authentication and shares the ceremony URL directly.
        - **identity_verification** -- The recipient proves their identity with an identity verification provider.

        You can combine multiple types for added security. For example, use custom authentication first, then email code as a second step. See the constraints below:

        - `email_link` can only be the first step.
        - `custom` can only be the first step.
        - `email_link` and `custom` cannot be combined together.
        - `identity_verification` can never be the first step, and can appear at most once. It is enabled per account.
      type: array
      minItems: 1
      maxItems: 5
      items:
        oneOf:
          - $ref: '#/components/schemas/Ceremony.EmailLinkAuthenticationInput'
          - $ref: '#/components/schemas/Ceremony.EmailCodeAuthenticationInput'
          - $ref: '#/components/schemas/Ceremony.CustomAuthenticationInput'
          - $ref: '#/components/schemas/Ceremony.IdentityVerificationAuthenticationInput'
      discriminator:
        propertyName: type
        mapping:
          email_link: '#/components/schemas/Ceremony.EmailLinkAuthenticationInput'
          email_code: '#/components/schemas/Ceremony.EmailCodeAuthenticationInput'
          custom: '#/components/schemas/Ceremony.CustomAuthenticationInput'
          identity_verification: '#/components/schemas/Ceremony.IdentityVerificationAuthenticationInput'
    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.

        Each recipient can have one active ceremony at a time. When you create a new ceremony for a recipient, any previous ceremonies are automatically revoked.

        ### Lifecycle

        A ceremony moves through the following statuses:

        - **pending** -- The ceremony is created but the envelope is not yet active.
        - **active** -- The ceremony is ready for the recipient to access.
        - **completed** -- The recipient finished their actions.
        - **declined** -- The recipient declined to act.
        - **revoked** -- The ceremony was replaced by a new one or canceled.

        ### Authentication

        Every ceremony requires at least one authentication method. You can combine multiple methods that the recipient must complete in sequence before accessing the ceremony.
      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
    Recipient.CeremonyInput:
      x-schema-role: property
      x-schema-direction: input
      title: Ceremony
      description: |
        Configuration for the first ceremony to create for the recipient.

        If 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.
      allOf:
        - $ref: '#/components/schemas/Ceremony.CeremonyInput'
    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.

        During 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.

        All signer actions are recorded in the audit log attached to the final deliverable.

        ### Delivery

        The `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.

        The signer receives an email with the ceremony link when the ceremony uses `email_link` authentication, which is the default.

        ### Signature options

        The `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.
      type: object
      additionalProperties: false
      properties:
        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.CeremonyInput'
        delivery_type:
          allOf:
            - $ref: '#/components/schemas/Recipient.DeliveryType'
            - default: email
        signature_options:
          $ref: '#/components/schemas/Recipient.SignatureOptions'
      required:
        - type
        - key
        - email
        - name
    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.

        The 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.

        Qualified 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.

        ### Delivery

        The `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.

        The qualified signer receives an email with the ceremony link when the ceremony uses `email_link` authentication, which is the default.

        ### Signature options

        The `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.
      type: object
      additionalProperties: false
      properties:
        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.CeremonyInput'
        delivery_type:
          allOf:
            - $ref: '#/components/schemas/Recipient.DeliveryType'
            - default: email
        signature_options:
          $ref: '#/components/schemas/Recipient.SignatureOptions'
        scheme:
          $ref: '#/components/schemas/Recipient.SignatureScheme'
      required:
        - type
        - key
        - email
        - name
        - scheme
    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.

        Use 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.

        Approver actions are not recorded in the audit log.

        ### Delivery

        The `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.

        The 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.
      type: object
      additionalProperties: false
      properties:
        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.CeremonyInput'
        delivery_type:
          allOf:
            - $ref: '#/components/schemas/Recipient.DeliveryType'
            - default: none
      required:
        - type
        - key
        - email
        - name
    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.

        Use preparers when someone needs to populate document data before a signer receives the envelope — for example, a sales representative entering pricing or contract terms.

        The values a preparer enters are visible to subsequent recipients in the routing order. Preparer actions are not recorded in the audit log.

        ### Delivery

        The `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.

        The 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.
      type: object
      additionalProperties: false
      properties:
        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.CeremonyInput'
        delivery_type:
          allOf:
            - $ref: '#/components/schemas/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: '#/components/schemas/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
            (created via `POST /v1/uploads`) and permanent uploads (stored via the
            Dashboard or via `POST /v1/uploads/{id}/store`) are accepted. The upload
            must not be expired.
          example: https://api.signatureapi.com/v1/uploads/upl_1sAAaVfabdt0esVjmSTmLA
      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.
      oneOf:
        - $ref: '#/components/schemas/Recipient.PresetSymbolDrawnInput'
      discriminator:
        propertyName: type
        mapping:
          drawn: '#/components/schemas/Recipient.PresetSymbolDrawnInput'
    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.
      type: object
      additionalProperties: false
      properties:
        type:
          allOf:
            - $ref: '#/components/schemas/Recipient.Type'
            - const: automatic_signer
        key:
          $ref: '#/components/schemas/Recipient.Key'
        name:
          $ref: '#/components/schemas/Recipient.Name'
        signature:
          $ref: '#/components/schemas/Recipient.PresetSymbolInput'
        initials:
          $ref: '#/components/schemas/Recipient.PresetSymbolInput'
        mandate:
          $ref: '#/components/schemas/Recipient.Mandate'
      required:
        - type
        - key
        - name
        - mandate
    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.

        Each recipient has a **type** that determines what they can do:

        - **Signer** — signs documents. This is the most common recipient type. Every envelope must have at least one signing recipient.
        - **Approver** — reviews and approves documents without signing them.
        - **Preparer** — fills in document fields before the signer receives them.
        - **Automatic Signer** — the signature is applied automatically by the system.

        The `type` field acts as a discriminator. The properties available on a recipient depend on its type.

        ### Routing

        Recipients 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.

        ### Lifecycle

        A 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.
      oneOf:
        - $ref: '#/components/schemas/Recipient.SignerInput'
        - $ref: '#/components/schemas/Recipient.QualifiedSignerInput'
        - $ref: '#/components/schemas/Recipient.ApproverInput'
        - $ref: '#/components/schemas/Recipient.PreparerInput'
        - $ref: '#/components/schemas/Recipient.AutomaticSignerInput'
      discriminator:
        propertyName: type
        mapping:
          signer: '#/components/schemas/Recipient.SignerInput'
          qualified_signer: '#/components/schemas/Recipient.QualifiedSignerInput'
          approver: '#/components/schemas/Recipient.ApproverInput'
          preparer: '#/components/schemas/Recipient.PreparerInput'
          automatic_signer: '#/components/schemas/Recipient.AutomaticSignerInput'
    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.

        Four recipient types are supported:

        - **signer** -- Signs the documents.
        - **preparer** -- Fills in fields before signers receive the documents.
        - **approver** -- Reviews and approves the documents without signing.
        - **automatic_signer** -- Has their signature applied automatically.

        The 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: '#/components/schemas/Recipient.RecipientInput'
    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.

        If omitted, the account's default sender name and email will be used.
      properties:
        name:
          $ref: '#/components/schemas/Envelope.SenderName'
        email:
          $ref: '#/components/schemas/Envelope.SenderEmail'
        organization:
          $ref: '#/components/schemas/Envelope.SenderOrganization'
    Envelope.EnvelopeInput:
      x-schema-role: model
      x-schema-direction: input
      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.

        ### Lifecycle

        An envelope moves through five statuses:

        1. `processing` -- The envelope is being prepared. Documents are validated and recipients are notified.
        2. `in_progress` -- The envelope has been sent to recipients and is waiting for all participants to complete their part.
        3. `completed` -- All recipients have completed their part (for example, signed). A **deliverable** is generated and sent to the recipients.
        4. `failed` -- An internal error occurred during processing. This is rare and triggers an automatic alert.
        5. `canceled` -- The signing process was intentionally stopped before completion via the Cancel Envelope endpoint.

        ### Relationships

        An envelope:

        - Has one or more **recipients** (signers, preparers, or approvers).
        - Has one or more **documents** (PDF or DOCX format).
        - Has one or more **deliverables** generated upon completion.
      type: object
      additionalProperties: false
      properties:
        label:
          $ref: '#/components/schemas/Envelope.Label'
        metadata:
          $ref: '#/components/schemas/Envelope.Metadata'
        message:
          $ref: '#/components/schemas/Envelope.Message'
        title:
          $ref: '#/components/schemas/Envelope.Title'
        topics:
          $ref: '#/components/schemas/Envelope.Topics'
        branding:
          $ref: '#/components/schemas/Envelope.BrandingInput'
        timezone:
          $ref: '#/components/schemas/Envelope.Timezone'
        timestamp_format:
          $ref: '#/components/schemas/Envelope.TimestampFormat'
        language:
          $ref: '#/components/schemas/Envelope.Language'
        routing:
          $ref: '#/components/schemas/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`.

            Two types are available:

            - `standard` -- Includes signed documents and an audit log.
            - `simple` -- Includes signed documents only, without an audit log.

            If no deliverable is provided, a `standard` deliverable is automatically generated.
          allOf:
            - $ref: '#/components/schemas/Deliverable.DeliverableInput'
        attestation:
          $ref: '#/components/schemas/Envelope.Attestation'
        documents:
          $ref: '#/components/schemas/Envelope.DocumentsInput'
        recipients:
          $ref: '#/components/schemas/Envelope.RecipientsInput'
        sender:
          $ref: '#/components/schemas/Envelope.SenderInput'
      required:
        - title
        - documents
        - recipients
    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.
      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
    Envelope.CancelReason:
      x-schema-role: property
      x-schema-direction: any
      type:
        - string
        - 'null'
      title: Envelope Cancel Reason
      description: |
        An optional explanation for why the envelope was canceled. This is for internal use only and is not shown to recipients.

        The reason is included in the `envelope.canceled` webhook event payload, making it available for your records and automated workflows.
      minLength: 1
      maxLength: 2000
      examples:
        - Mars is full. No more explorers allowed.
    Event.TypeForEnvelope:
      x-schema-role: property
      x-schema-direction: output
      type: string
      description: The type of the event. When listing envelope events, the available types include envelope, recipient, and deliverable events associated with that envelope.
      x-enum-descriptions:
        envelope.created: A new envelope was created.
        envelope.started: The envelope finished processing and is ready to send to recipients.
        envelope.completed: All recipients completed (for example, signed) the envelope.
        envelope.failed: The envelope encountered an error and moved to a failed status.
        envelope.canceled: The envelope was canceled through the Cancel Envelope endpoint.
        recipient.released: The recipient is ready to receive a signing request. Status changed to pending.
        recipient.sent: The signing request email was delivered to the recipient.
        recipient.accessed: The recipient entered the signing ceremony.
        recipient.identity_verification_started: The recipient was sent to the identity verification provider.
        recipient.identity_verified: The identity verification provider confirmed the recipient's identity.
        recipient.identity_rejected: The identity verification provider did not confirm the recipient's identity.
        recipient.viewed: The recipient authenticated and viewed the documents.
        recipient.completed: The recipient finished signing. Status changed to completed.
        recipient.soft_bounced: The email to the recipient temporarily bounced (for example, full mailbox).
        recipient.hard_bounced: The email to the recipient permanently bounced (for example, invalid address).
        recipient.rejected: The recipient declined the envelope.
        recipient.failed: The recipient encountered a general failure.
        recipient.replaced: The recipient was replaced with a new recipient.
        recipient.resent: The signing request was resent to the recipient.
        deliverable.generated: The signed document was generated and is available for download.
        deliverable.failed: The signed document failed to generate.
      example: recipient.completed
      enum:
        - envelope.created
        - envelope.started
        - envelope.completed
        - envelope.failed
        - envelope.canceled
        - recipient.released
        - recipient.sent
        - recipient.accessed
        - recipient.identity_verification_started
        - recipient.identity_verified
        - recipient.identity_rejected
        - recipient.viewed
        - recipient.completed
        - recipient.soft_bounced
        - recipient.hard_bounced
        - recipient.rejected
        - recipient.failed
        - recipient.replaced
        - recipient.resent
        - deliverable.generated
        - deliverable.failed
    Event.Id:
      x-schema-role: property
      x-schema-direction: output
      type: string
      description: Unique identifier for the event. Uses the `evt_` prefix.
      example: evt_1sAAaVfabdt0esVjmSTmLA
    Event.Timestamp:
      x-schema-role: property
      x-schema-direction: output
      title: Event Timestamp
      description: When the event occurred, in ISO 8601 format.
      example: '2025-07-15T14:30:00Z'
      type: string
      format: date-time
    Event.EventBase:
      x-schema-role: property
      x-schema-direction: output
      description: Base properties shared by all events. Every event includes a unique identifier and a timestamp recording when the event occurred.
      type: object
      properties:
        id:
          $ref: '#/components/schemas/Event.Id'
        timestamp:
          $ref: '#/components/schemas/Event.Timestamp'
      required:
        - id
        - timestamp
    Event.Type:
      x-schema-role: property
      x-schema-direction: output
      type: string
      description: 'The type of the event. Determines the category and the shape of the `data` payload. Event types are grouped into four categories: envelope, recipient, deliverable, and sender.'
      x-enum-descriptions:
        envelope.created: A new envelope was created.
        envelope.started: The envelope finished processing and is ready to send to recipients.
        envelope.completed: All recipients completed (for example, signed) the envelope.
        envelope.failed: The envelope encountered an error and moved to a failed status.
        envelope.canceled: The envelope was canceled through the Cancel Envelope endpoint.
        recipient.released: The recipient is ready to receive a signing request. Status changed to pending.
        recipient.sent: The signing request email was delivered to the recipient.
        recipient.accessed: The recipient entered the signing ceremony.
        recipient.identity_verification_started: The recipient was sent to the identity verification provider.
        recipient.identity_verified: The identity verification provider confirmed the recipient's identity.
        recipient.identity_rejected: The identity verification provider did not confirm the recipient's identity.
        recipient.viewed: The recipient authenticated and viewed the documents.
        recipient.completed: The recipient finished signing. Status changed to completed.
        recipient.soft_bounced: The email to the recipient temporarily bounced (for example, full mailbox).
        recipient.hard_bounced: The email to the recipient permanently bounced (for example, invalid address).
        recipient.rejected: The recipient declined the envelope.
        recipient.failed: The recipient encountered a general failure.
        recipient.replaced: The recipient was replaced with a new recipient.
        recipient.resent: The signing request was resent to the recipient.
        deliverable.generated: The signed document was generated and is available for download.
        deliverable.failed: The signed document failed to generate.
        sender.created: A verification request was initiated for a sender.
        sender.verified: The sender completed email verification.
        sender.failed: The sender verification failed.
        sender.deleted: The sender was deleted.
      example: envelope.completed
      enum:
        - envelope.created
        - envelope.started
        - envelope.completed
        - envelope.failed
        - envelope.canceled
        - recipient.released
        - recipient.sent
        - recipient.accessed
        - recipient.identity_verification_started
        - recipient.identity_verified
        - recipient.identity_rejected
        - recipient.viewed
        - recipient.completed
        - recipient.soft_bounced
        - recipient.hard_bounced
        - recipient.rejected
        - recipient.failed
        - recipient.replaced
        - recipient.resent
        - deliverable.generated
        - deliverable.failed
        - sender.created
        - sender.verified
        - sender.failed
        - sender.deleted
    Event.ObjectType:
      x-schema-role: property
      x-schema-direction: output
      type: string
      description: The type of object this event refers to. Indicates whether the event relates to an envelope, recipient, deliverable, or sender.
      x-enum-descriptions:
        envelope: The event relates to an envelope.
        recipient: The event relates to a recipient.
        deliverable: The event relates to a deliverable (signed document).
        sender: The event relates to a sender.
      example: envelope
      enum:
        - envelope
        - recipient
        - deliverable
        - sender
    Event.EnvelopeEventData:
      x-schema-role: property
      x-schema-direction: output
      type: object
      description: Data payload for envelope events. Contains the envelope identifier, object type, and any metadata attached to the envelope.
      properties:
        envelope_id:
          $ref: '#/components/schemas/Envelope.Id'
        object_type:
          allOf:
            - $ref: '#/components/schemas/Event.ObjectType'
            - const: envelope
        object_id:
          $ref: '#/components/schemas/Envelope.Id'
        envelope_metadata:
          $ref: '#/components/schemas/Envelope.Metadata'
      required:
        - envelope_id
        - object_type
        - object_id
        - envelope_metadata
    Event.EnvelopeCreated:
      x-schema-role: model
      x-schema-direction: output
      title: Envelope Created Event
      description: Fired when a new envelope is created. This is the first event in the envelope lifecycle.
      allOf:
        - $ref: '#/components/schemas/Event.EventBase'
        - type: object
          required:
            - type
            - data
          properties:
            type:
              allOf:
                - $ref: '#/components/schemas/Event.Type'
                - const: envelope.created
            data:
              allOf:
                - $ref: '#/components/schemas/Event.EnvelopeEventData'
    Event.EnvelopeStarted:
      x-schema-role: model
      x-schema-direction: output
      title: Envelope Started Event
      description: Fired when the envelope finishes processing and is ready to send to recipients. The envelope status changes from `processing` to `in_progress`.
      allOf:
        - $ref: '#/components/schemas/Event.EventBase'
        - type: object
          required:
            - type
            - data
          properties:
            type:
              allOf:
                - $ref: '#/components/schemas/Event.Type'
                - const: envelope.started
            data:
              allOf:
                - $ref: '#/components/schemas/Event.EnvelopeEventData'
    Event.EnvelopeCompleted:
      x-schema-role: model
      x-schema-direction: output
      title: Envelope Completed Event
      description: Fired when all recipients have completed (for example, signed) the envelope. The envelope status changes from `in_progress` to `completed`.
      allOf:
        - $ref: '#/components/schemas/Event.EventBase'
        - type: object
          required:
            - type
            - data
          properties:
            type:
              allOf:
                - $ref: '#/components/schemas/Event.Type'
                - const: envelope.completed
            data:
              allOf:
                - $ref: '#/components/schemas/Event.EnvelopeEventData'
    Envelope.FailDetail:
      x-schema-role: property
      x-schema-direction: output
      type: string
      title: Envelope Fail Detail
      description: |
        A human-readable explanation of what caused the envelope to fail. This detail is included in the `envelope.failed` webhook event payload. Failures are very rare and automatically trigger an alert to the SignatureAPI team.
      examples:
        - Could not parse input PDF document.
    Event.EnvelopeFailed:
      x-schema-role: model
      x-schema-direction: output
      title: Envelope Failed Event
      description: Fired when the envelope encounters an error. The envelope status changes to `failed`. The `data.detail` field contains the reason for the failure.
      allOf:
        - $ref: '#/components/schemas/Event.EventBase'
        - type: object
          required:
            - type
            - data
          properties:
            type:
              allOf:
                - $ref: '#/components/schemas/Event.Type'
                - const: envelope.failed
            data:
              allOf:
                - $ref: '#/components/schemas/Event.EnvelopeEventData'
                - type: object
                  properties:
                    detail:
                      $ref: '#/components/schemas/Envelope.FailDetail'
                  required:
                    - detail
    Event.EnvelopeCanceled:
      x-schema-role: model
      x-schema-direction: output
      title: Envelope Canceled Event
      description: Fired when the envelope is canceled through the Cancel Envelope endpoint. The envelope status changes to `canceled`. The `data.reason` field contains the cancellation reason, if one was provided.
      allOf:
        - $ref: '#/components/schemas/Event.EventBase'
        - type: object
          required:
            - type
            - data
          properties:
            type:
              allOf:
                - $ref: '#/components/schemas/Event.Type'
                - const: envelope.canceled
            data:
              allOf:
                - $ref: '#/components/schemas/Event.EnvelopeEventData'
                - type: object
                  properties:
                    reason:
                      $ref: '#/components/schemas/Envelope.CancelReason'
                  required:
                    - reason
    Event.RecipientEventData:
      x-schema-role: property
      x-schema-direction: output
      type: object
      description: Data payload for recipient events. Contains the recipient identifier, the parent envelope identifier, envelope metadata, and recipient details such as type and key.
      properties:
        envelope_id:
          $ref: '#/components/schemas/Envelope.Id'
        object_type:
          allOf:
            - $ref: '#/components/schemas/Event.ObjectType'
            - const: recipient
        object_id:
          $ref: '#/components/schemas/Recipient.Id'
        envelope_metadata:
          $ref: '#/components/schemas/Envelope.Metadata'
        recipient_type:
          $ref: '#/components/schemas/Recipient.Type'
        recipient_key:
          $ref: '#/components/schemas/Recipient.Key'
      required:
        - envelope_id
        - object_type
        - object_id
        - envelope_metadata
        - recipient_type
        - recipient_key
    Event.RecipientReleased:
      x-schema-role: model
      x-schema-direction: output
      title: Recipient Released Event
      description: Fired when a recipient is ready to receive a signing request. The recipient status changes to `pending`.
      allOf:
        - $ref: '#/components/schemas/Event.EventBase'
        - type: object
          required:
            - type
            - data
          properties:
            type:
              allOf:
                - $ref: '#/components/schemas/Event.Type'
                - const: recipient.released
            data:
              allOf:
                - $ref: '#/components/schemas/Event.RecipientEventData'
    Event.RecipientSent:
      x-schema-role: model
      x-schema-direction: output
      title: Recipient Sent Event
      description: Fired when the signing request email is delivered to the recipient.
      allOf:
        - $ref: '#/components/schemas/Event.EventBase'
        - type: object
          required:
            - type
            - data
          properties:
            type:
              allOf:
                - $ref: '#/components/schemas/Event.Type'
                - const: recipient.sent
            data:
              allOf:
                - $ref: '#/components/schemas/Event.RecipientEventData'
    Recipient.IP:
      x-schema-role: property
      x-schema-direction: output
      type: string
      title: Recipient IP Address
      description: |
        The IP address of the recipient when they accessed the ceremony. Captured from the recipient's browser session.

        Available in `recipient.accessed` events.
      examples:
        - 123.122.990.22
        - 2001:0db8:85a3:0000:0000:8a2e:0370:7334
    Recipient.UserAgent:
      x-schema-role: property
      x-schema-direction: output
      type: string
      title: Recipient User Agent
      description: |
        The browser user agent string of the recipient when they accessed the ceremony. Identifies the recipient's browser and operating system.

        Available in `recipient.accessed` events.
      examples:
        - Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36
    Recipient.SessionId:
      x-schema-role: property
      x-schema-direction: output
      type: string
      title: Recipient Session ID
      description: |
        A unique identifier for the recipient's ceremony session. Use this to correlate multiple events from the same session, such as `recipient.accessed`, `recipient.viewed`, and `recipient.completed`.
      examples:
        - ses_2X6eHBCL84MDGrLQX0mHI72
    Event.RecipientAccessed:
      x-schema-role: model
      x-schema-direction: output
      title: Recipient Accessed Event
      description: Fired when the recipient enters the signing ceremony. Emitted at most once every 60 seconds per IP address and user agent to reduce duplicates. The `data` includes the recipient's IP address, user agent, and session ID.
      allOf:
        - $ref: '#/components/schemas/Event.EventBase'
        - type: object
          required:
            - type
            - data
          properties:
            type:
              allOf:
                - $ref: '#/components/schemas/Event.Type'
                - const: recipient.accessed
            data:
              allOf:
                - $ref: '#/components/schemas/Event.RecipientEventData'
                - type: object
                  properties:
                    ip:
                      $ref: '#/components/schemas/Recipient.IP'
                    user_agent:
                      $ref: '#/components/schemas/Recipient.UserAgent'
                    session_id:
                      $ref: '#/components/schemas/Recipient.SessionId'
                  required:
                    - ip
                    - user_agent
                    - session_id
    Event.RecipientIdentityVerificationStarted:
      x-schema-role: model
      x-schema-direction: output
      title: Recipient Identity Verification Started Event
      description: Fired when the recipient is sent to the identity verification provider. Nothing is proven yet at this point. The `data` includes the verification `method` and the `provider` handling the check.
      allOf:
        - $ref: '#/components/schemas/Event.EventBase'
        - type: object
          required:
            - type
            - data
          properties:
            type:
              allOf:
                - $ref: '#/components/schemas/Event.Type'
                - const: recipient.identity_verification_started
            data:
              allOf:
                - $ref: '#/components/schemas/Event.RecipientEventData'
                - type: object
                  properties:
                    method:
                      $ref: '#/components/schemas/Ceremony.IdentityVerificationMethod'
                    provider:
                      $ref: '#/components/schemas/Ceremony.IdentityVerificationProvider'
                  required:
                    - method
                    - provider
    Ceremony.IdentityEvidenceReference:
      x-schema-role: property
      x-schema-direction: output
      type: string
      title: Identity Evidence Reference
      description: |
        The provider's own handle on the completed verification. Quote this value back to the provider to retrieve the underlying proof.

        This reference never carries personal data. It appears in the `recipient.identity_verified` and `recipient.identity_rejected` events and in the envelope audit log.
      example: stub-9f2c1f6a2e6b4d1f9c0a
    Event.RecipientIdentityVerified:
      x-schema-role: model
      x-schema-direction: output
      title: Recipient Identity Verified Event
      description: Fired when the identity verification provider confirms the recipient's identity. The `data` includes the verification `method`, the `provider`, and the `evidence_reference` the provider left behind.
      allOf:
        - $ref: '#/components/schemas/Event.EventBase'
        - type: object
          required:
            - type
            - data
          properties:
            type:
              allOf:
                - $ref: '#/components/schemas/Event.Type'
                - const: recipient.identity_verified
            data:
              allOf:
                - $ref: '#/components/schemas/Event.RecipientEventData'
                - type: object
                  properties:
                    method:
                      $ref: '#/components/schemas/Ceremony.IdentityVerificationMethod'
                    provider:
                      $ref: '#/components/schemas/Ceremony.IdentityVerificationProvider'
                    evidence_reference:
                      $ref: '#/components/schemas/Ceremony.IdentityEvidenceReference'
                  required:
                    - method
                    - provider
    Event.RecipientIdentityRejected:
      x-schema-role: model
      x-schema-direction: output
      title: Recipient Identity Rejected Event
      description: Fired when the identity verification provider does not confirm the recipient's identity. The recipient can retry until the attempt cap is reached. The `data` includes the verification `method`, the `provider`, and the `evidence_reference` the provider left behind.
      allOf:
        - $ref: '#/components/schemas/Event.EventBase'
        - type: object
          required:
            - type
            - data
          properties:
            type:
              allOf:
                - $ref: '#/components/schemas/Event.Type'
                - const: recipient.identity_rejected
            data:
              allOf:
                - $ref: '#/components/schemas/Event.RecipientEventData'
                - type: object
                  properties:
                    method:
                      $ref: '#/components/schemas/Ceremony.IdentityVerificationMethod'
                    provider:
                      $ref: '#/components/schemas/Ceremony.IdentityVerificationProvider'
                    evidence_reference:
                      $ref: '#/components/schemas/Ceremony.IdentityEvidenceReference'
                  required:
                    - method
                    - provider
    Event.RecipientViewed:
      x-schema-role: model
      x-schema-direction: output
      title: Recipient Viewed Event
      description: Fired after the recipient authenticates and views the documents in the signing ceremony. The `data` includes the session ID.
      allOf:
        - $ref: '#/components/schemas/Event.EventBase'
        - type: object
          required:
            - type
            - data
          properties:
            type:
              allOf:
                - $ref: '#/components/schemas/Event.Type'
                - const: recipient.viewed
            data:
              allOf:
                - $ref: '#/components/schemas/Event.RecipientEventData'
                - type: object
                  properties:
                    session_id:
                      $ref: '#/components/schemas/Recipient.SessionId'
                  required:
                    - session_id
    Event.RecipientCompleted:
      x-schema-role: model
      x-schema-direction: output
      title: Recipient Completed Event
      description: Fired when the recipient finishes signing. The recipient status changes to `completed`. The `data` includes the session ID.
      allOf:
        - $ref: '#/components/schemas/Event.EventBase'
        - type: object
          required:
            - type
            - data
          properties:
            type:
              allOf:
                - $ref: '#/components/schemas/Event.Type'
                - const: recipient.completed
            data:
              allOf:
                - $ref: '#/components/schemas/Event.RecipientEventData'
                - type: object
                  properties:
                    session_id:
                      $ref: '#/components/schemas/Recipient.SessionId'
    Recipient.BounceDetail:
      x-schema-role: property
      x-schema-direction: output
      type: string
      title: Recipient Bounce Detail
      description: |
        A human-readable explanation of why the email bounced. Contains information from the remote email server, such as "Mailbox Full" or "User Unknown."

        Present when the recipient status is `soft_bounced` or `hard_bounced`.
      examples:
        - 'Permanent/General, diagnostic code: smtp; 550 5.1.1 As requested: user unknown <bounce+mlkav@example.com>'
    Event.RecipientSoftBounced:
      x-schema-role: model
      x-schema-direction: output
      title: Recipient Soft Bounced Event
      description: Fired when the email to the recipient temporarily bounces. Common causes include a full mailbox or a temporary server issue. The `data.detail` field contains the bounce reason.
      allOf:
        - $ref: '#/components/schemas/Event.EventBase'
        - type: object
          required:
            - type
            - data
          properties:
            type:
              allOf:
                - $ref: '#/components/schemas/Event.Type'
                - const: recipient.soft_bounced
            data:
              allOf:
                - $ref: '#/components/schemas/Event.RecipientEventData'
                - type: object
                  properties:
                    detail:
                      $ref: '#/components/schemas/Recipient.BounceDetail'
                  required:
                    - detail
    Event.RecipientHardBounced:
      x-schema-role: model
      x-schema-direction: output
      title: Recipient Hard Bounced Event
      description: Fired when the email to the recipient permanently bounces. Common causes include an invalid email address. After a hard bounce, you cannot send additional requests to this recipient without using the Replace Recipient endpoint. The `data.detail` field contains the bounce reason.
      allOf:
        - $ref: '#/components/schemas/Event.EventBase'
        - type: object
          required:
            - type
            - data
          properties:
            type:
              allOf:
                - $ref: '#/components/schemas/Event.Type'
                - const: recipient.hard_bounced
            data:
              allOf:
                - $ref: '#/components/schemas/Event.RecipientEventData'
                - type: object
                  properties:
                    detail:
                      $ref: '#/components/schemas/Recipient.BounceDetail'
                  required:
                    - detail
    Recipient.RejectReason:
      x-schema-role: property
      x-schema-direction: output
      type: string
      title: Recipient Reject Reason
      description: |
        An explanation provided by the recipient for rejecting the envelope. The recipient may optionally enter a reason during the ceremony when they decline to sign.

        Present when the recipient status is `rejected`. May be empty if the recipient did not provide a reason.
      maxLength: 2000
      examples:
        - Not the terms we agreed to on June.
    Event.RecipientRejected:
      x-schema-role: model
      x-schema-direction: output
      title: Recipient Rejected Event
      description: Fired when the recipient declines the envelope. The `data.reason` field contains the rejection reason if the recipient provided one. The `data` includes the session ID.
      allOf:
        - $ref: '#/components/schemas/Event.EventBase'
        - type: object
          required:
            - type
            - data
          properties:
            type:
              allOf:
                - $ref: '#/components/schemas/Event.Type'
                - const: recipient.rejected
            data:
              allOf:
                - $ref: '#/components/schemas/Event.RecipientEventData'
                - type: object
                  properties:
                    reason:
                      $ref: '#/components/schemas/Recipient.RejectReason'
                    session_id:
                      $ref: '#/components/schemas/Recipient.SessionId'
                  required:
                    - reason
                    - session_id
    Recipient.FailDetail:
      x-schema-role: property
      x-schema-direction: output
      type: string
      title: Recipient Fail Detail
      description: |
        A human-readable explanation of why the recipient failed. For example, the recipient's email may be on a blocklist.

        Present when the recipient status is `failed`.
      examples:
        - Recipient in email blocklist.
    Event.RecipientFailed:
      x-schema-role: model
      x-schema-direction: output
      title: Recipient Failed Event
      description: Fired when the recipient encounters a general failure. The `data.detail` field contains the failure reason.
      allOf:
        - $ref: '#/components/schemas/Event.EventBase'
        - type: object
          required:
            - type
            - data
          properties:
            type:
              allOf:
                - $ref: '#/components/schemas/Event.Type'
                - const: recipient.failed
            data:
              allOf:
                - $ref: '#/components/schemas/Event.RecipientEventData'
                - type: object
                  properties:
                    detail:
                      $ref: '#/components/schemas/Recipient.FailDetail'
                  required:
                    - detail
    Event.RecipientReplaced:
      x-schema-role: model
      x-schema-direction: output
      title: Recipient Replaced Event
      description: Fired when the recipient is replaced with a new recipient through the Replace Recipient endpoint. The `data` includes the new recipient's ID and name.
      allOf:
        - $ref: '#/components/schemas/Event.EventBase'
        - type: object
          required:
            - type
            - data
          properties:
            type:
              allOf:
                - $ref: '#/components/schemas/Event.Type'
                - const: recipient.replaced
            data:
              allOf:
                - $ref: '#/components/schemas/Event.RecipientEventData'
                - type: object
                  properties:
                    new_recipient_id:
                      $ref: '#/components/schemas/Recipient.Id'
                    new_recipient_name:
                      $ref: '#/components/schemas/Recipient.Name'
                  required:
                    - new_recipient_id
                    - new_recipient_name
    Event.RecipientResent:
      x-schema-role: model
      x-schema-direction: output
      title: Recipient Resent Event
      description: Fired when the signing request is resent to the recipient.
      allOf:
        - $ref: '#/components/schemas/Event.EventBase'
        - type: object
          required:
            - type
            - data
          properties:
            type:
              allOf:
                - $ref: '#/components/schemas/Event.Type'
                - const: recipient.resent
            data:
              allOf:
                - $ref: '#/components/schemas/Event.RecipientEventData'
    Event.DeliverableEventData:
      x-schema-role: property
      x-schema-direction: output
      type: object
      description: Data payload for deliverable events. Contains the deliverable identifier, the parent envelope identifier, envelope metadata, deliverable type, name, and the list of included documents.
      properties:
        envelope_id:
          $ref: '#/components/schemas/Envelope.Id'
        object_type:
          allOf:
            - $ref: '#/components/schemas/Event.ObjectType'
            - const: deliverable
        object_id:
          $ref: '#/components/schemas/Deliverable.Id'
        envelope_metadata:
          $ref: '#/components/schemas/Envelope.Metadata'
        deliverable_type:
          $ref: '#/components/schemas/Deliverable.Type'
        deliverable_name:
          $ref: '#/components/schemas/Deliverable.Name'
        included_documents:
          $ref: '#/components/schemas/Deliverable.IncludedDocuments'
      required:
        - envelope_id
        - object_type
        - object_id
        - envelope_metadata
        - deliverable_type
        - deliverable_name
        - included_documents
    Event.DeliverableGenerated:
      x-schema-role: model
      x-schema-direction: output
      title: Deliverable Generated Event
      description: Fired when the signed document is generated and available for download. The `data.url` field contains a pre-signed, short-lived download link. If the link expires, retrieve a new one through the Get Deliverable endpoint.
      allOf:
        - $ref: '#/components/schemas/Event.EventBase'
        - type: object
          required:
            - type
            - data
          properties:
            type:
              allOf:
                - $ref: '#/components/schemas/Event.Type'
                - const: deliverable.generated
            data:
              allOf:
                - $ref: '#/components/schemas/Event.DeliverableEventData'
                - type: object
                  properties:
                    url:
                      $ref: '#/components/schemas/Deliverable.Url'
                  required:
                    - url
    Deliverable.FailDetail:
      x-schema-role: property
      x-schema-direction: output
      type: string
      title: Deliverable Fail Detail
      description: A human-readable explanation of why the deliverable failed to generate. Only present when the deliverable status is `failed`.
      examples:
        - Recipient in email blocklist.
    Event.DeliverableFailed:
      x-schema-role: model
      x-schema-direction: output
      title: Deliverable Failed Event
      description: Fired when the signed document fails to generate. The `data.detail` field contains the failure reason.
      allOf:
        - $ref: '#/components/schemas/Event.EventBase'
        - type: object
          required:
            - type
            - data
          properties:
            type:
              allOf:
                - $ref: '#/components/schemas/Event.Type'
                - const: deliverable.failed
            data:
              allOf:
                - $ref: '#/components/schemas/Event.DeliverableEventData'
                - type: object
                  properties:
                    detail:
                      $ref: '#/components/schemas/Deliverable.FailDetail'
                  required:
                    - detail
    Event.EnvelopeContextEvent:
      x-schema-role: model
      x-schema-direction: output
      title: Envelope Event
      description: An event associated with an envelope. Includes envelope events, recipient events, and deliverable events that occurred in the context of a specific envelope. The `type` field determines which event schema applies.
      oneOf:
        - $ref: '#/components/schemas/Event.EnvelopeCreated'
        - $ref: '#/components/schemas/Event.EnvelopeStarted'
        - $ref: '#/components/schemas/Event.EnvelopeCompleted'
        - $ref: '#/components/schemas/Event.EnvelopeFailed'
        - $ref: '#/components/schemas/Event.EnvelopeCanceled'
        - $ref: '#/components/schemas/Event.RecipientReleased'
        - $ref: '#/components/schemas/Event.RecipientSent'
        - $ref: '#/components/schemas/Event.RecipientAccessed'
        - $ref: '#/components/schemas/Event.RecipientIdentityVerificationStarted'
        - $ref: '#/components/schemas/Event.RecipientIdentityVerified'
        - $ref: '#/components/schemas/Event.RecipientIdentityRejected'
        - $ref: '#/components/schemas/Event.RecipientViewed'
        - $ref: '#/components/schemas/Event.RecipientCompleted'
        - $ref: '#/components/schemas/Event.RecipientSoftBounced'
        - $ref: '#/components/schemas/Event.RecipientHardBounced'
        - $ref: '#/components/schemas/Event.RecipientRejected'
        - $ref: '#/components/schemas/Event.RecipientFailed'
        - $ref: '#/components/schemas/Event.RecipientReplaced'
        - $ref: '#/components/schemas/Event.RecipientResent'
        - $ref: '#/components/schemas/Event.DeliverableGenerated'
        - $ref: '#/components/schemas/Event.DeliverableFailed'
      discriminator:
        propertyName: type
        mapping:
          envelope.created: '#/components/schemas/Event.EnvelopeCreated'
          envelope.started: '#/components/schemas/Event.EnvelopeStarted'
          envelope.completed: '#/components/schemas/Event.EnvelopeCompleted'
          envelope.failed: '#/components/schemas/Event.EnvelopeFailed'
          envelope.canceled: '#/components/schemas/Event.EnvelopeCanceled'
          recipient.released: '#/components/schemas/Event.RecipientReleased'
          recipient.sent: '#/components/schemas/Event.RecipientSent'
          recipient.accessed: '#/components/schemas/Event.RecipientAccessed'
          recipient.identity_verification_started: '#/components/schemas/Event.RecipientIdentityVerificationStarted'
          recipient.identity_verified: '#/components/schemas/Event.RecipientIdentityVerified'
          recipient.identity_rejected: '#/components/schemas/Event.RecipientIdentityRejected'
          recipient.viewed: '#/components/schemas/Event.RecipientViewed'
          recipient.completed: '#/components/schemas/Event.RecipientCompleted'
          recipient.soft_bounced: '#/components/schemas/Event.RecipientSoftBounced'
          recipient.hard_bounced: '#/components/schemas/Event.RecipientHardBounced'
          recipient.rejected: '#/components/schemas/Event.RecipientRejected'
          recipient.failed: '#/components/schemas/Event.RecipientFailed'
          recipient.replaced: '#/components/schemas/Event.RecipientReplaced'
          recipient.resent: '#/components/schemas/Event.RecipientResent'
          deliverable.generated: '#/components/schemas/Event.DeliverableGenerated'
          deliverable.failed: '#/components/schemas/Event.DeliverableFailed'
    Event.TypeForRecipient:
      x-schema-role: property
      x-schema-direction: output
      type: string
      description: The type of the event. When listing recipient events, only recipient event types are available.
      x-enum-descriptions:
        recipient.released: The recipient is ready to receive a signing request. Status changed to pending.
        recipient.sent: The signing request email was delivered to the recipient.
        recipient.accessed: The recipient entered the signing ceremony.
        recipient.identity_verification_started: The recipient was sent to the identity verification provider.
        recipient.identity_verified: The identity verification provider confirmed the recipient's identity.
        recipient.identity_rejected: The identity verification provider did not confirm the recipient's identity.
        recipient.viewed: The recipient authenticated and viewed the documents.
        recipient.completed: The recipient finished signing. Status changed to completed.
        recipient.soft_bounced: The email to the recipient temporarily bounced (for example, full mailbox).
        recipient.hard_bounced: The email to the recipient permanently bounced (for example, invalid address).
        recipient.rejected: The recipient declined the envelope.
        recipient.failed: The recipient encountered a general failure.
        recipient.replaced: The recipient was replaced with a new recipient.
        recipient.resent: The signing request was resent to the recipient.
      example: recipient.completed
      enum:
        - recipient.released
        - recipient.sent
        - recipient.accessed
        - recipient.identity_verification_started
        - recipient.identity_verified
        - recipient.identity_rejected
        - recipient.viewed
        - recipient.completed
        - recipient.soft_bounced
        - recipient.hard_bounced
        - recipient.rejected
        - recipient.failed
        - recipient.replaced
        - recipient.resent
    Event.RecipientEvent:
      x-schema-role: model
      x-schema-direction: output
      description: An event associated with a recipient. Tracks the recipient's progress through the signing lifecycle, from release to completion, as well as delivery issues and actions like replacement or resending. The `type` field determines which event schema applies.
      oneOf:
        - $ref: '#/components/schemas/Event.RecipientReleased'
        - $ref: '#/components/schemas/Event.RecipientSent'
        - $ref: '#/components/schemas/Event.RecipientAccessed'
        - $ref: '#/components/schemas/Event.RecipientIdentityVerificationStarted'
        - $ref: '#/components/schemas/Event.RecipientIdentityVerified'
        - $ref: '#/components/schemas/Event.RecipientIdentityRejected'
        - $ref: '#/components/schemas/Event.RecipientViewed'
        - $ref: '#/components/schemas/Event.RecipientCompleted'
        - $ref: '#/components/schemas/Event.RecipientSoftBounced'
        - $ref: '#/components/schemas/Event.RecipientHardBounced'
        - $ref: '#/components/schemas/Event.RecipientRejected'
        - $ref: '#/components/schemas/Event.RecipientFailed'
        - $ref: '#/components/schemas/Event.RecipientReplaced'
        - $ref: '#/components/schemas/Event.RecipientResent'
      discriminator:
        propertyName: type
        mapping:
          recipient.released: '#/components/schemas/Event.RecipientReleased'
          recipient.sent: '#/components/schemas/Event.RecipientSent'
          recipient.accessed: '#/components/schemas/Event.RecipientAccessed'
          recipient.identity_verification_started: '#/components/schemas/Event.RecipientIdentityVerificationStarted'
          recipient.identity_verified: '#/components/schemas/Event.RecipientIdentityVerified'
          recipient.identity_rejected: '#/components/schemas/Event.RecipientIdentityRejected'
          recipient.viewed: '#/components/schemas/Event.RecipientViewed'
          recipient.completed: '#/components/schemas/Event.RecipientCompleted'
          recipient.soft_bounced: '#/components/schemas/Event.RecipientSoftBounced'
          recipient.hard_bounced: '#/components/schemas/Event.RecipientHardBounced'
          recipient.rejected: '#/components/schemas/Event.RecipientRejected'
          recipient.failed: '#/components/schemas/Event.RecipientFailed'
          recipient.replaced: '#/components/schemas/Event.RecipientReplaced'
          recipient.resent: '#/components/schemas/Event.RecipientResent'
    Sender.Id:
      x-schema-role: property
      x-schema-direction: output
      type: string
      title: Sender ID
      description: The unique identifier of the sender.
      examples:
        - a1b2c3d4-e5f6-7890-abcd-ef1234567890
    Sender.Email:
      x-schema-role: property
      x-schema-direction: any
      title: Sender Email
      description: The email address of the sender. SignatureAPI sends signing request emails to recipients on behalf of this address.
      type: string
      format: email
      maxLength: 320
      example: john@example.com
    Event.SenderEventData:
      x-schema-role: property
      x-schema-direction: output
      type: object
      description: Data payload for sender events. Contains the sender identifier, object type, and the sender's email address.
      properties:
        object_type:
          allOf:
            - $ref: '#/components/schemas/Event.ObjectType'
            - const: sender
        object_id:
          $ref: '#/components/schemas/Sender.Id'
        email:
          $ref: '#/components/schemas/Sender.Email'
      required:
        - object_type
        - object_id
        - email
    Event.SenderCreated:
      x-schema-role: model
      x-schema-direction: output
      title: Sender Created Event
      description: Fired when a verification request is initiated for a sender email address.
      allOf:
        - $ref: '#/components/schemas/Event.EventBase'
        - type: object
          required:
            - type
            - data
          properties:
            type:
              allOf:
                - $ref: '#/components/schemas/Event.Type'
                - const: sender.created
            data:
              allOf:
                - $ref: '#/components/schemas/Event.SenderEventData'
    Event.SenderVerified:
      x-schema-role: model
      x-schema-direction: output
      title: Sender Verified Event
      description: Fired when the sender completes email verification.
      allOf:
        - $ref: '#/components/schemas/Event.EventBase'
        - type: object
          required:
            - type
            - data
          properties:
            type:
              allOf:
                - $ref: '#/components/schemas/Event.Type'
                - const: sender.verified
            data:
              allOf:
                - $ref: '#/components/schemas/Event.SenderEventData'
    Sender.FailDetail:
      x-schema-role: property
      x-schema-direction: output
      type: string
      title: Sender Fail Detail
      description: A human-readable explanation of why sender verification failed. Possible reasons include a hard or soft bounce of the verification email, or an internal error.
      examples:
        - Verification email bounced
    Event.SenderFailed:
      x-schema-role: model
      x-schema-direction: output
      title: Sender Failed Event
      description: Fired when sender verification fails. The `data.detail` field contains the failure reason, such as an undeliverable verification email.
      allOf:
        - $ref: '#/components/schemas/Event.EventBase'
        - type: object
          required:
            - type
            - data
          properties:
            type:
              allOf:
                - $ref: '#/components/schemas/Event.Type'
                - const: sender.failed
            data:
              allOf:
                - $ref: '#/components/schemas/Event.SenderEventData'
                - type: object
                  properties:
                    detail:
                      $ref: '#/components/schemas/Sender.FailDetail'
                  required:
                    - detail
    Event.SenderDeleted:
      x-schema-role: model
      x-schema-direction: output
      title: Sender Deleted Event
      description: Fired when a sender is deleted from the account.
      allOf:
        - $ref: '#/components/schemas/Event.EventBase'
        - type: object
          required:
            - type
            - data
          properties:
            type:
              allOf:
                - $ref: '#/components/schemas/Event.Type'
                - const: sender.deleted
            data:
              allOf:
                - $ref: '#/components/schemas/Event.SenderEventData'
    Event.Event:
      x-schema-role: model
      x-schema-direction: output
      title: Event
      description: 'An event records a change or action in your account. Each event has a `type` field that determines its category and the shape of its `data` payload. Events fall into four categories: envelope events, recipient events, deliverable events, and sender events. You can receive events through webhooks or retrieve them through the API.'
      oneOf:
        - $ref: '#/components/schemas/Event.EnvelopeCreated'
        - $ref: '#/components/schemas/Event.EnvelopeStarted'
        - $ref: '#/components/schemas/Event.EnvelopeCompleted'
        - $ref: '#/components/schemas/Event.EnvelopeFailed'
        - $ref: '#/components/schemas/Event.EnvelopeCanceled'
        - $ref: '#/components/schemas/Event.RecipientReleased'
        - $ref: '#/components/schemas/Event.RecipientSent'
        - $ref: '#/components/schemas/Event.RecipientAccessed'
        - $ref: '#/components/schemas/Event.RecipientIdentityVerificationStarted'
        - $ref: '#/components/schemas/Event.RecipientIdentityVerified'
        - $ref: '#/components/schemas/Event.RecipientIdentityRejected'
        - $ref: '#/components/schemas/Event.RecipientViewed'
        - $ref: '#/components/schemas/Event.RecipientCompleted'
        - $ref: '#/components/schemas/Event.RecipientSoftBounced'
        - $ref: '#/components/schemas/Event.RecipientHardBounced'
        - $ref: '#/components/schemas/Event.RecipientRejected'
        - $ref: '#/components/schemas/Event.RecipientFailed'
        - $ref: '#/components/schemas/Event.RecipientReplaced'
        - $ref: '#/components/schemas/Event.RecipientResent'
        - $ref: '#/components/schemas/Event.DeliverableGenerated'
        - $ref: '#/components/schemas/Event.DeliverableFailed'
        - $ref: '#/components/schemas/Event.SenderCreated'
        - $ref: '#/components/schemas/Event.SenderVerified'
        - $ref: '#/components/schemas/Event.SenderFailed'
        - $ref: '#/components/schemas/Event.SenderDeleted'
      discriminator:
        propertyName: type
        mapping:
          envelope.created: '#/components/schemas/Event.EnvelopeCreated'
          envelope.started: '#/components/schemas/Event.EnvelopeStarted'
          envelope.completed: '#/components/schemas/Event.EnvelopeCompleted'
          envelope.failed: '#/components/schemas/Event.EnvelopeFailed'
          envelope.canceled: '#/components/schemas/Event.EnvelopeCanceled'
          recipient.released: '#/components/schemas/Event.RecipientReleased'
          recipient.sent: '#/components/schemas/Event.RecipientSent'
          recipient.accessed: '#/components/schemas/Event.RecipientAccessed'
          recipient.identity_verification_started: '#/components/schemas/Event.RecipientIdentityVerificationStarted'
          recipient.identity_verified: '#/components/schemas/Event.RecipientIdentityVerified'
          recipient.identity_rejected: '#/components/schemas/Event.RecipientIdentityRejected'
          recipient.viewed: '#/components/schemas/Event.RecipientViewed'
          recipient.completed: '#/components/schemas/Event.RecipientCompleted'
          recipient.soft_bounced: '#/components/schemas/Event.RecipientSoftBounced'
          recipient.hard_bounced: '#/components/schemas/Event.RecipientHardBounced'
          recipient.rejected: '#/components/schemas/Event.RecipientRejected'
          recipient.failed: '#/components/schemas/Event.RecipientFailed'
          recipient.replaced: '#/components/schemas/Event.RecipientReplaced'
          recipient.resent: '#/components/schemas/Event.RecipientResent'
          deliverable.generated: '#/components/schemas/Event.DeliverableGenerated'
          deliverable.failed: '#/components/schemas/Event.DeliverableFailed'
          sender.created: '#/components/schemas/Event.SenderCreated'
          sender.verified: '#/components/schemas/Event.SenderVerified'
          sender.failed: '#/components/schemas/Event.SenderFailed'
          sender.deleted: '#/components/schemas/Event.SenderDeleted'
    Upload.Id:
      x-schema-role: property
      x-schema-direction: output
      type: string
      title: Upload ID
      description: The unique identifier of the upload.
      example: upl_1sAAaVfabdt0esVjmSTmLA
    Upload.Retention:
      x-schema-role: property
      x-schema-direction: output
      title: Retention
      description: |
        The retention type of the upload.

        - `temporary` -- The file is automatically deleted after 24 hours. Created through the API.
        - `permanent` -- The file is stored indefinitely. Created through the dashboard library.
      example: temporary
      type: string
      enum:
        - temporary
        - permanent
    Upload.Url:
      x-schema-role: property
      x-schema-direction: output
      title: URL
      description: |
        A URL used to reference the uploaded file.

        This internal URL can be used as input in other fields, like `document.url`.

        The file's content cannot be retrieved directly via this URL.
      type: string
      format: uri
      example: https://api.signatureapi.com/v1/uploads/upl_3joO7lxE8HVhOZmkCHFCxK
    Upload.Sha256:
      x-schema-role: property
      x-schema-direction: output
      title: SHA-256 Hash
      description: The SHA-256 hash of the uploaded file in hexadecimal format.
      type: string
      example: 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
    Upload.Size:
      x-schema-role: property
      x-schema-direction: output
      title: Size
      description: The size of the uploaded file in bytes. Maximum 5 MB (5,242,880 bytes).
      type: integer
      example: 102400
    Upload.Format:
      x-schema-role: property
      x-schema-direction: output
      type: string
      title: Format
      description: |
        The file format of the upload.

        - `pdf` -- A PDF file (`application/pdf`).
        - `docx` -- A DOCX file (`application/vnd.openxmlformats-officedocument.wordprocessingml.document`).
        - `png` -- A PNG image (`image/png`).
      example: pdf
      enum:
        - pdf
        - docx
        - png
    Upload.CreatedAt:
      x-schema-role: property
      x-schema-direction: output
      title: Created At
      description: The date and time when the upload was created, in ISO 8601 format.
      type: string
      format: date-time
      example: '2025-12-31T00:00:00.000Z'
    Upload.ExpiresAt:
      x-schema-role: property
      x-schema-direction: output
      title: Expires At
      description: |
        The date and time when the temporary upload expires and is automatically deleted, in ISO 8601 format. Only present on temporary uploads. The expiration is 24 hours after creation.
      type: string
      format: date-time
      example: '2025-12-31T00:00:00.000Z'
    Upload.TemporaryUpload:
      x-schema-role: model
      x-schema-direction: output
      title: Temporary Upload
      description: |
        A temporary upload stored in SignatureAPI for 24 hours. Temporary uploads are created through the API and automatically deleted when they expire. Best for one-time use when creating an envelope.
      type: object
      properties:
        id:
          $ref: '#/components/schemas/Upload.Id'
        retention:
          allOf:
            - $ref: '#/components/schemas/Upload.Retention'
            - const: temporary
        url:
          $ref: '#/components/schemas/Upload.Url'
        sha_256:
          $ref: '#/components/schemas/Upload.Sha256'
        size:
          $ref: '#/components/schemas/Upload.Size'
        format:
          $ref: '#/components/schemas/Upload.Format'
        created_at:
          $ref: '#/components/schemas/Upload.CreatedAt'
        expires_at:
          $ref: '#/components/schemas/Upload.ExpiresAt'
      required:
        - id
        - retention
        - url
        - sha_256
        - size
        - format
        - created_at
        - expires_at
    Upload.Key:
      x-schema-role: property
      x-schema-direction: any
      title: Upload Key
      description: |
        A unique key that identifies the permanent upload within your account. Only lowercase letters, numbers, hyphens, and underscores are allowed. Maximum 100 characters.
      pattern: ^[a-z0-9_-]+$
      maxLength: 100
      type: string
      example: contract-template-v2
    Upload.PermanentUpload:
      x-schema-role: model
      x-schema-direction: output
      title: Permanent Upload
      description: |
        A permanent upload stored in SignatureAPI indefinitely. Permanent uploads are created through the dashboard library and can be reused across multiple envelopes. Each permanent upload has a unique `key` for identification.
      type: object
      properties:
        id:
          $ref: '#/components/schemas/Upload.Id'
        retention:
          allOf:
            - $ref: '#/components/schemas/Upload.Retention'
            - const: permanent
        key:
          $ref: '#/components/schemas/Upload.Key'
        url:
          $ref: '#/components/schemas/Upload.Url'
        sha_256:
          $ref: '#/components/schemas/Upload.Sha256'
        size:
          $ref: '#/components/schemas/Upload.Size'
        format:
          $ref: '#/components/schemas/Upload.Format'
        created_at:
          $ref: '#/components/schemas/Upload.CreatedAt'
      required:
        - id
        - retention
        - key
        - url
        - sha_256
        - size
        - format
        - created_at
    Upload.Upload:
      x-schema-role: model
      x-schema-direction: output
      description: |
        An **upload** is a file stored in SignatureAPI that can be used as a document source in an envelope.

        Uploads support two file formats: **PDF** and **DOCX**. The maximum file size is 5 MB.

        ### Retention

        Uploads have one of two retention types:

        - **Temporary** -- Created through the API. Automatically deleted after 24 hours. Best for one-time use.
        - **Permanent** -- Created through the dashboard library. Stored indefinitely and reusable across multiple envelopes. Identified by a unique `key`.

        ### Usage

        After uploading a file, use the returned `url` value as the document source when creating an envelope. This URL is an internal reference and cannot be used to download the file directly.

        ### Structure

        Use the **Get Upload Structure** endpoint to inspect the internal structure of an uploaded file. The structure includes page dimensions, detected **placeholders**, and -- for DOCX templates -- detected **template fields**.
      oneOf:
        - $ref: '#/components/schemas/Upload.TemporaryUpload'
        - $ref: '#/components/schemas/Upload.PermanentUpload'
      discriminator:
        propertyName: retention
        mapping:
          permanent: '#/components/schemas/Upload.PermanentUpload'
          temporary: '#/components/schemas/Upload.TemporaryUpload'
    Sender.SenderInput:
      x-schema-role: model
      x-schema-direction: input
      title: Sender Input
      description: |
        A **sender** is a verified email address that SignatureAPI sends signing requests on behalf of. Each sender must complete email verification before it can be used with envelopes.

        When you create a sender, SignatureAPI sends a verification email to the provided address. The sender starts in `pending_verification` status. Once the email owner clicks the confirmation link, the status changes to `verified`. If the verification email bounces or encounters an error, the status changes to `failed`.

        Only senders with `verified` status can be used as the sender on an envelope.
      type: object
      additionalProperties: false
      properties:
        email:
          $ref: '#/components/schemas/Sender.Email'
      required:
        - email
    Sender.Status:
      x-schema-role: property
      x-schema-direction: output
      title: Sender Status
      description: |
        The current verification status of the sender.

        - `pending_verification` — A verification email has been sent but the sender has not yet confirmed.
        - `verified` — The sender confirmed the verification email and can be used to send envelopes.
        - `failed` — The verification email bounced or encountered an error. This sender cannot be used.
      type: string
      enum:
        - pending_verification
        - verified
        - failed
      examples:
        - verified
    Sender.CreatedAt:
      x-schema-role: property
      x-schema-direction: output
      type: string
      format: date-time
      title: Sender Created At
      description: Time at which the sender was created. Formatted as an ISO 8601 timestamp.
      examples:
        - '2025-01-01T00:00:00.000Z'
    Sender.Sender:
      x-schema-role: model
      x-schema-direction: output
      title: Sender
      description: |
        A **sender** is a verified email address that SignatureAPI sends signing requests on behalf of. Each sender must complete email verification before it can be used with envelopes.

        When you create a sender, SignatureAPI sends a verification email to the provided address. The sender starts in `pending_verification` status. Once the email owner clicks the confirmation link, the status changes to `verified`. If the verification email bounces or encounters an error, the status changes to `failed`.

        Only senders with `verified` status can be used as the sender on an envelope.
      type: object
      additionalProperties: false
      properties:
        id:
          $ref: '#/components/schemas/Sender.Id'
        email:
          $ref: '#/components/schemas/Sender.Email'
        status:
          $ref: '#/components/schemas/Sender.Status'
        created_at:
          $ref: '#/components/schemas/Sender.CreatedAt'
      required:
        - id
        - email
        - status
        - created_at
  parameters:
    EnvelopeStatus:
      name: status
      in: query
      description: Filter by envelope status.
      required: false
      schema:
        $ref: '#/components/schemas/Envelope.Status'
    EnvelopeTopic:
      name: topic
      in: query
      description: Filter by envelope topic.
      required: false
      schema:
        $ref: '#/components/schemas/Envelope.Topic'
    PaginationLimit:
      name: limit
      in: query
      description: The maximum number of objects to return in the response.
      schema:
        type: integer
        minimum: 1
        maximum: 20
        default: 20
    EnvelopeId:
      name: envelopeId
      in: path
      description: The unique identifier of an envelope.
      required: true
      schema:
        $ref: '#/components/schemas/Envelope.Id'
    EnvelopeEventType:
      name: type
      in: query
      description: Filter by event type.
      required: false
      schema:
        $ref: '#/components/schemas/Event.TypeForEnvelope'
    RecipientId:
      name: recipientId
      in: path
      description: The unique identifier of a recipient.
      required: true
      schema:
        $ref: '#/components/schemas/Recipient.Id'
    RecipientEventType:
      name: type
      in: query
      description: Filter by event type.
      required: false
      schema:
        $ref: '#/components/schemas/Event.TypeForRecipient'
    DeliverableId:
      name: deliverableId
      in: path
      description: The unique identifier of a deliverable.
      required: true
      schema:
        $ref: '#/components/schemas/Deliverable.Id'
    EventType:
      name: type
      in: query
      description: Filter by event type.
      required: false
      schema:
        $ref: '#/components/schemas/Event.Type'
    UploadId:
      name: uploadId
      in: path
      description: The unique identifier of an upload.
      required: true
      schema:
        $ref: '#/components/schemas/Upload.Id'
    SenderId:
      name: senderId
      in: path
      description: The unique identifier of a sender.
      required: true
      schema:
        $ref: '#/components/schemas/Sender.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.

        This error covers HTTP status codes in the 400 to 499 range. The most common are:

        - 401 Unauthorized
        - 403 Forbidden
        - 409 Conflict
        - 410 Gone
        - 404 Not Found
        - 422 Unprocessable Content.
      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.
      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.
    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.
      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
