> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firma.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Signing Request

> Create a new signing request either from a PDF document (document-based) or from an existing template (template-based). For document-based creation, allow_editing_before_sending is automatically set to true. For template-based creation, properties are inherited from the template and can be overridden.

**Temporary ID Pattern**: For document-based creation, you can reference recipients before they're created using temporary IDs (format: 'temp_X' where X is any identifier, e.g., 'temp_1', 'temp_alice'). Use these temporary IDs in recipient.id, field.recipient_id, and reminder.recipient_id. The API validates all references and automatically maps temporary IDs to real UUIDs after recipients are created. The response contains only real UUIDs.

**Temporary ID Validation**: Temporary IDs must start with 'temp_', be unique across all recipients in the request, and all field/reminder references must point to recipients defined in the same request. Invalid format, duplicate IDs, or missing recipient references return a 400 error with detailed validation messages.



## OpenAPI

````yaml api-reference/v01.20.00/openapi-v01.20.00.json post /signing-requests
openapi: 3.0.3
info:
  title: Firma Partner API
  description: >-
    RESTful API for document signing and template management.


    **Authentication**: All endpoints require API key authentication via the
    `Authorization` header. Use your API key directly without any prefix (e.g.,
    `your-api-key`). The Bearer prefix is optional but not required.


    **Security Features**:

    - Input validation using Zod schemas with detailed field-level error
    messages

    - RSA-256 signed JWT tokens for embedded template access


    **Rate Limiting**: Rate limits are tiered based on operation type:

    - Read operations (GET): 200 requests per minute

    - Write operations (POST/PUT/PATCH/DELETE): 120 requests per minute

    - Webhook CRUD operations: 60 requests per minute

    - Webhook test: 10 requests per minute

    - API key regeneration/expiration: 1 request per minute

    - Webhook secret rotation: 1 request per minute


    When rate limits are exceeded, the API returns a `429 Too Many Requests`
    response with headers:

    - `X-RateLimit-Limit`: Maximum requests per minute for this endpoint

    - `X-RateLimit-Remaining`: Requests remaining in current window

    - `X-RateLimit-Reset`: Unix timestamp when limit resets

    - `Retry-After`: Seconds until retry is allowed


    **Error Handling**: All errors return structured JSON responses with `error`
    (human-readable message), `code` (machine-readable identifier), and
    `details` (field-level validation errors when applicable).


    **Embedded Template Integration**: The Firma Template Editor can be embedded
    in your application using a standalone JavaScript library.


    ```html

    <!-- Load the Firma Template Editor library -->

    <script
    src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>


    <script>

    // Generate JWT token via API first

    fetch('https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
    {
      method: 'POST',
      headers: {
        'Authorization': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        companies_workspaces_templates_id: 'template-id'
      })
    })

    .then(res => res.json())

    .then(data => {
      // Initialize editor with JWT token
      window.FirmaTemplateEditor.init({
        container: '#firma-editor-container',
        jwt: data.token,
        templateId: 'template-id',
        theme: 'dark',
        readOnly: false,
        onSave: (savedData) => {
          console.log('Template saved:', savedData);
        },
        onError: (error) => {
          console.error('Editor error:', error);
        },
        onLoad: (template) => {
          console.log('Template loaded:', template);
        }
      });
    });

    ```
  version: 01.20.00
  contact:
    name: API Support
    url: https://firma.com/support
servers:
  - url: https://api.firma.dev/functions/v1/signing-request-api
    description: Production API - Recommended (Current)
  - url: https://api.firma.dev/api/v1
    description: Production API - Planned
security:
  - ApiKeyAuth: []
tags:
  - name: Company
    description: Company information and settings
  - name: Workspaces
    description: Workspace management operations
  - name: Templates
    description: Template management operations
  - name: Signing Requests
    description: Document signing request operations
  - name: Custom Fields
    description: >-
      Custom field definition management for workspaces, templates, and signing
      requests
  - name: Webhooks
    description: Webhook configuration and management
  - name: JWT Management
    description: JWT token generation and revocation for embedded templates
  - name: Workspace Settings
    description: Workspace configuration and settings
  - name: Email Domains
    description: >-
      Email domain setup and verification for sending signing request emails
      from custom domains
  - name: Email Templates
    description: >-
      Email template management for workspace and company-level customization of
      signing request notifications
  - name: Legacy
    description: Deprecated endpoints maintained for backward compatibility
paths:
  /signing-requests:
    post:
      tags:
        - Signing Requests
      summary: Create Signing Request
      description: >-
        Create a new signing request either from a PDF document (document-based)
        or from an existing template (template-based). For document-based
        creation, allow_editing_before_sending is automatically set to true. For
        template-based creation, properties are inherited from the template and
        can be overridden.


        **Temporary ID Pattern**: For document-based creation, you can reference
        recipients before they're created using temporary IDs (format: 'temp_X'
        where X is any identifier, e.g., 'temp_1', 'temp_alice'). Use these
        temporary IDs in recipient.id, field.recipient_id, and
        reminder.recipient_id. The API validates all references and
        automatically maps temporary IDs to real UUIDs after recipients are
        created. The response contains only real UUIDs.


        **Temporary ID Validation**: Temporary IDs must start with 'temp_', be
        unique across all recipients in the request, and all field/reminder
        references must point to recipients defined in the same request. Invalid
        format, duplicate IDs, or missing recipient references return a 400
        error with detailed validation messages.
      requestBody:
        $ref: '#/components/requestBodies/PatchSigningRequestBody'
      responses:
        '201':
          description: >-
            Signing request created successfully. Response may include a
            'warnings' array for email format validation warnings
            (non-blocking).
          headers:
            X-RateLimit-Limit:
              schema:
                type: integer
              description: 'Rate limit: 120 requests per minute'
            X-RateLimit-Remaining:
              schema:
                type: integer
            X-RateLimit-Reset:
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SigningRequestCreateResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
          description: >-
            Invalid input - must provide either 'document' or 'template_id', not
            both. Document must be valid base64-encoded PDF under 20MB. Template
            must exist and belong to workspace.
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          description: Template not found or does not belong to workspace
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/RateLimitError'
      security:
        - ApiKeyAuth: []
components:
  requestBodies:
    PatchSigningRequestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PatchSigningRequestBodySchema'
          examples:
            update-properties:
              summary: Update properties
              value:
                name: Updated Contract Name
                expiration_hours: 72
            update-recipient:
              summary: Update single recipient
              value:
                recipient:
                  id: rec123-e89b-12d3-a456-426614174000
                  first_name: John
                  last_name: Smith
                  email: john.smith@example.com
                  designation: Signer
                  order: 1
            add-recipient:
              summary: Add new recipient
              value:
                recipient:
                  first_name: Jane
                  last_name: Doe
                  email: jane@example.com
                  designation: Signer
                  order: 2
            add-date-field:
              summary: Add date field with formatting
              value:
                field:
                  type: date
                  position:
                    x: 70
                    'y': 45
                    width: 15
                    height: 3
                  page_number: 1
                  required: true
                  recipient_id: rec123-e89b-12d3-a456-426614174000
                  date_signing_default: true
                  format_rules:
                    dateFormat: MMMM dd, yyyy
            add-read-only-static-field:
              summary: Add read-only field with static value
              description: >-
                Creates a text field that displays a fixed value the signer
                cannot edit
              value:
                field:
                  type: text
                  position:
                    x: 15
                    'y': 20
                    width: 40
                    height: 3
                  page_number: 1
                  required: false
                  recipient_id: rec123-e89b-12d3-a456-426614174000
                  read_only: true
                  read_only_value: 'Contract #12345 - Acme Corporation'
            add-read-only-prefilled-field:
              summary: Add read-only field with recipient data
              description: >-
                Creates a text field that auto-populates with the recipient's
                email address (signer cannot edit)
              value:
                field:
                  type: text
                  position:
                    x: 15
                    'y': 30
                    width: 30
                    height: 3
                  page_number: 1
                  required: false
                  recipient_id: rec123-e89b-12d3-a456-426614174000
                  read_only: true
                  prefilled_data: email
  schemas:
    SigningRequestCreateResponse:
      type: object
      description: >-
        Signing request as returned by CREATE endpoints (POST /signing-requests,
        POST /documents)
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the signing request
        name:
          type: string
          description: Signing request name
          maxLength: 255
        description:
          type: string
          nullable: true
          description: Signing request description
        status:
          type: string
          enum:
            - draft
          description: Status is always 'draft' for newly created signing requests
        document_url:
          type: string
          format: uri
          description: Pre-signed URL to the PDF document
        page_count:
          type: integer
          minimum: 1
          description: Number of pages in the document
        expiration_hours:
          type: integer
          minimum: 1
          default: 168
          description: 'Hours until signing request expires (default: 168 = 7 days)'
        template_id:
          type: string
          format: uuid
          nullable: true
          description: Template ID if created from a template
        settings:
          $ref: '#/components/schemas/SigningRequestSettings'
        created_date:
          type: string
          format: date-time
          description: Creation timestamp
        updated_date:
          type: string
          format: date-time
          description: Last update timestamp
        sent_date:
          type: string
          format: date-time
          nullable: true
          description: When the signing request was sent
        finished_date:
          type: string
          format: date-time
          nullable: true
          description: When all signatures were completed
        cancelled_date:
          type: string
          format: date-time
          nullable: true
          description: When the signing request was cancelled
        recipients:
          type: array
          description: Signing request recipients
          items:
            $ref: '#/components/schemas/SigningRequestCreateRecipient'
        fields:
          type: array
          description: Signing request fields with flat position values
          items:
            $ref: '#/components/schemas/SigningRequestCreateField'
        warnings:
          type: array
          items:
            type: string
          description: >-
            Optional email format validation warnings. Only present when
            recipient emails have unusual formats.
    Error:
      type: object
      properties:
        error:
          type: string
          description: Human-readable error message
        message:
          type: string
          description: Detailed error description
        details:
          type: object
          description: Additional error details
          additionalProperties: true
    PatchSigningRequestBodySchema:
      oneOf:
        - type: object
          required:
            - document
          description: Create signing request from a PDF document
          properties:
            document:
              type: string
              format: byte
              description: >-
                Base64-encoded PDF or DOCX document. DOCX files are
                automatically converted to PDF. Page count will be
                auto-extracted.
            name:
              type: string
              maxLength: 255
              description: Name for the signing request
            description:
              type: string
              description: Description for the signing request
            expiration_hours:
              type: integer
              minimum: 1
              default: 168
              description: 'Hours until the signing request expires (default: 168 = 7 days)'
            recipients:
              type: array
              items:
                $ref: '#/components/schemas/Recipient'
              description: >-
                Recipients for the signing request. Use temporary IDs (e.g.,
                'temp_1') in the id field to reference recipients in
                fields/reminders.
            fields:
              type: array
              items:
                $ref: '#/components/schemas/Field'
              description: >-
                Fields to place on the document. Use recipient_id to assign
                fields to recipients.
            anchor_tags:
              type: array
              maxItems: 100
              items:
                $ref: '#/components/schemas/AnchorTag'
              description: >-
                Anchor tags for automatic field placement. Text markers in the
                PDF are located and converted to positioned fields. The anchor
                text is removed from the PDF after processing. Fields created
                from anchor tags are added alongside any manually specified
                fields. Only available for document-based creation (not
                template-based).
            reminders:
              type: array
              items:
                $ref: '#/components/schemas/SigningRequestReminder'
              description: Reminders to send to recipients
            settings:
              $ref: '#/components/schemas/SigningRequestSettings'
              description: Signing request settings
        - type: object
          required:
            - template_id
          description: >-
            Create signing request from a template. Supports partial updates for
            both recipients and fields.
          properties:
            template_id:
              type: string
              format: uuid
              description: >-
                ID of the template to create signing request from. The document,
                fields, and default recipients will be copied from the template.
            name:
              type: string
              maxLength: 255
              description: >-
                Custom name for signing request (defaults to template name if
                not provided)
            description:
              type: string
              description: >-
                Custom description (defaults to template description if not
                provided)
            expiration_hours:
              type: integer
              minimum: 1
              description: Override template expiration hours
            recipients:
              type: array
              items:
                $ref: '#/components/schemas/Recipient'
              description: >-
                Optional recipient overrides. Use template_user_id (preferred)
                or order (fallback) to match template users. Only user info
                (first_name, last_name, email, phone_number, address fields,
                title, company) can be updated - order and designation are
                always inherited from template. Recipients not provided will use
                template defaults.
            fields:
              type: array
              items:
                $ref: '#/components/schemas/Field'
              description: >-
                Optional field overrides for partial updates. Use
                template_field_id (preferred) or variable_name (fallback) to
                match template fields. Only provided properties override
                template defaults. Supported override properties: type,
                required, position, read_only, read_only_value, format_rules,
                validation_rules, dropdown_options, date_default,
                date_signing_default, multi_group_id. Fields not matched are
                ignored. If fields array is omitted, all template fields are
                used as-is.
            settings:
              $ref: '#/components/schemas/SigningRequestSettings'
              description: Override template settings
          example:
            template_id: 21424147-11c0-43d5-ac5f-a1f7001b5607
            name: Contract for Client X
            recipients:
              - template_user_id: template-user-uuid-1
                first_name: Toni
                last_name: Campins
                email: acampins@cocodin.com
            fields:
              - template_field_id: field-uuid-1
                read_only: true
                read_only_value: 'Contract #12345'
              - variable_name: company_name
                read_only_value: Acme Corporation
    SigningRequestSettings:
      type: object
      description: >-
        Signing request and template settings. All 9 fields are returned by
        every endpoint that includes settings.
      properties:
        allow_download:
          type: boolean
          description: Whether recipients can download the document
          default: true
        attach_pdf_on_finish:
          type: boolean
          description: Whether to attach PDF when signing is complete
          default: true
        allow_editing_before_sending:
          type: boolean
          description: Whether the signing request can be edited before sending
          default: false
        use_signing_order:
          type: boolean
          description: >-
            Whether signing order is enforced among recipients. When true,
            signers receive the document in sequence based on their order. When
            false, all signers receive the document simultaneously.
          default: true
        hand_drawn_only:
          type: boolean
          description: >-
            When enabled, signers can only hand-draw their signatures and cannot
            use typed/font-based signatures
          default: false
        send_signing_email:
          type: boolean
          description: Whether to send signing request notification emails to signers
          default: true
        send_finish_email:
          type: boolean
          description: Whether to send completion email when all signers finish
          default: true
        send_expiration_email:
          type: boolean
          description: Whether to send expiration notification email when request expires
          default: true
        send_cancellation_email:
          type: boolean
          description: >-
            Whether to send cancellation notification email when request is
            cancelled
          default: true
        require_otp_verification:
          type: boolean
          nullable: true
          description: >-
            Whether signers must verify their email with a one-time code before
            accessing the document. null = inherit from workspace/company
            setting.
          default: null
        disable_guided_navigation:
          type: boolean
          nullable: true
          description: >-
            Disable automatic scrolling to the next required field during
            signing. Inherits from workspace or company if not set.
    SigningRequestCreateRecipient:
      type: object
      description: Recipient as returned in CREATE signing request responses
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the recipient
        first_name:
          type: string
          nullable: true
          description: Recipient first name
        last_name:
          type: string
          nullable: true
          description: Recipient last name
        name:
          type: string
          nullable: true
          description: Combined full name (auto-constructed from first_name + last_name)
        email:
          type: string
          format: email
          description: Recipient email address
        designation:
          type: string
          enum:
            - Signer
            - Approver
            - CC
          description: >-
            Role of the recipient. Signer signs the document, Approver approves
            with approval fields, CC receives a copy when complete.
        order:
          type: integer
          minimum: 1
          description: Signing order
        phone_number:
          type: string
          nullable: true
          description: Recipient phone number
        street_address:
          type: string
          nullable: true
          description: Street address
        city:
          type: string
          nullable: true
          description: City
        state_province:
          type: string
          nullable: true
          description: State or province
        postal_code:
          type: string
          nullable: true
          description: Postal code
        country:
          type: string
          nullable: true
          description: Country
        title:
          type: string
          nullable: true
          description: Job title
        company:
          type: string
          nullable: true
          description: Company name
        custom_fields:
          type: object
          nullable: true
          description: Custom key-value pairs
        finished_date:
          type: string
          format: date-time
          nullable: true
          description: When this recipient completed signing
    SigningRequestCreateField:
      type: object
      description: >-
        Field as returned in CREATE signing request responses (flat position,
        database-style)
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the field
        type:
          type: string
          enum:
            - text
            - signature
            - date
            - checkbox
            - dropdown
            - radio_buttons
            - number
            - text_area
            - file
            - initial
            - stamp
            - approval_signature
            - approval_checkmark
            - approval_date
          description: Type of the field
        recipient_id:
          type: string
          format: uuid
          nullable: true
          description: ID of assigned recipient
        page_number:
          type: integer
          minimum: 1
          description: Page number (1-indexed)
        x_position:
          type: number
          description: X coordinate as percentage (0-100)
        y_position:
          type: number
          description: Y coordinate as percentage (0-100)
        width:
          type: number
          description: Width as percentage (0-100)
        height:
          type: number
          description: Height as percentage (0-100)
        required:
          type: boolean
          description: Whether the field is required
        read_only:
          type: boolean
          description: Whether this field is read-only
        read_only_value:
          type: string
          nullable: true
          description: Static value for read-only fields
        variable_name:
          type: string
          nullable: true
          description: Variable name for prefilled data mapping
        variable_defined_name:
          type: string
          nullable: true
          description: >-
            Human-readable field name from the custom field definition (e.g.
            'artist_name'). Only present for fields linked to a custom field
            definition, null otherwise.
        dropdown_options:
          type: array
          items:
            type: string
          nullable: true
          description: Options for dropdown fields
        format_rules:
          type: object
          nullable: true
          description: Formatting rules (e.g., date format)
        validation_rules:
          type: object
          nullable: true
          description: Validation rules for the field
        date_signing_default:
          type: boolean
          description: Whether to use signing date as default
        final_value:
          type: string
          nullable: true
          description: Pre-filled or final value of the field
    Recipient:
      type: object
      required:
        - first_name
        - email
        - designation
      description: >-
        Recipient schema with auto-construction and mapping behaviors. **Name
        field**: Auto-constructed from first_name and last_name ('First Last' if
        both present, otherwise 'First'). Manual name values are overwritten.
        **Order assignment**: ALL recipients MUST have an explicit order value.
        Order determines the signing sequence, which is always enforced.
        Recipients must sign in order, with lower numbers signing first.
        **Custom fields**: Supports both flat structure (e.g., company_name at
        root) and nested structure (custom_fields object). Both formats are
        normalized internally. **Template field mapping**: When creating from a
        template with custom recipients, use template_user_id or order to match
        template users. Only user info (name, email, phone, etc.) can be updated
        - order and designation are inherited from template. **Temporary IDs**:
        For document-based creation, use temporary IDs (format: 'temp_1',
        'temp_2', etc.) to reference recipients in fields and reminders before
        they're created. **CC recipients**: CC recipients receive a completed
        copy but cannot sign or have fields assigned. At least one Signer is
        required.
      properties:
        id:
          type: string
          description: >-
            Unique identifier. For updates: use existing UUID. For
            document-based creation: optionally use temporary ID (format:
            'temp_1', 'temp_2', etc.) to reference recipients in fields and
            reminders before creation. Temporary IDs are automatically resolved
            to real UUIDs in the response.
        _temp_id:
          type: string
          description: >-
            Temporary identifier for new recipients in PUT (comprehensive
            update) requests (e.g., 'temp_1'). Use this when creating new
            recipients alongside existing ones in comprehensive updates. Must
            start with 'temp_' and be unique within the request. Not used for
            POST (create) requests - use 'id' field instead.
        template_user_id:
          type: string
          format: uuid
          description: >-
            When creating from a template, the ID of the template user to
            update. If provided, this recipient's data will update the matching
            template user. If not provided, falls back to matching by order.
            Only user info (name, email, phone, address, title, company) can be
            updated - order and designation are always inherited from the
            template.
        first_name:
          type: string
          maxLength: 100
          description: Recipient's first name
        last_name:
          type: string
          maxLength: 100
          description: >-
            Recipient's last name (optional, but required if using full_name or
            last_name prefilled variables)
        email:
          type: string
          format: email
          maxLength: 255
          description: Recipient's email address
        designation:
          type: string
          enum:
            - Signer
            - Approver
            - CC
          description: >-
            Role of the recipient. Signer signs the document, Approver approves
            with approval fields, CC receives a copy when complete.
        order:
          type: integer
          minimum: 1
          description: >-
            Signing sequence number. Recipients must sign in order, with lower
            numbers signing first. This field is required for all recipients.
        phone_number:
          type: string
          maxLength: 50
          nullable: true
          description: Recipient's phone number
        street_address:
          type: string
          maxLength: 255
          nullable: true
          description: Street address
        city:
          type: string
          maxLength: 100
          nullable: true
          description: City
        state_province:
          type: string
          maxLength: 100
          nullable: true
          description: State or province
        postal_code:
          type: string
          maxLength: 20
          nullable: true
          description: Postal/ZIP code
        country:
          type: string
          maxLength: 100
          nullable: true
          description: Country
        title:
          type: string
          maxLength: 100
          nullable: true
          description: Job title
        company:
          type: string
          maxLength: 255
          nullable: true
          description: Company name
        custom_fields:
          type: object
          additionalProperties: true
          description: Custom key-value pairs for additional recipient data
    Field:
      type: object
      required:
        - type
        - position
        - page_number
      description: >-
        Field definition for signing requests. **Read-only fields**: Set
        read_only=true to pre-fill a field value that signers cannot edit. Use
        read_only_value for static text, or prefilled_data to auto-populate from
        recipient attributes. **Template-based field merging**: When creating
        from a template with fields array, use template_field_id (preferred) or
        variable_name (fallback) to match template fields. Only provided
        properties override template defaults (partial update). Fields not
        matched are ignored.
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier (include for updates, omit for new fields)
        template_field_id:
          type: string
          format: uuid
          description: >-
            Template field ID to match for partial updates (template-based
            creation only). Use this to identify which template field to
            override. Takes precedence over variable_name for matching.
        type:
          type: string
          enum:
            - signature
            - text
            - date
            - checkbox
            - dropdown
            - initial
            - initials
            - text_area
            - textarea
            - image
            - stamp
            - approval_signature
            - approval_checkmark
            - approval_date
          description: >-
            Type of field. Accepts 'initial' or 'initials' (normalized to
            'initial'), 'textarea' or 'text_area' (normalized to 'text_area').
        position:
          type: object
          required:
            - x
            - 'y'
            - width
            - height
          description: >-
            Field must fit within page bounds: x + width <= 100 and y + height
            <= 100
          properties:
            x:
              type: number
              minimum: 0
              maximum: 100
              description: X coordinate as percentage (0-100)
            'y':
              type: number
              minimum: 0
              maximum: 100
              description: Y coordinate as percentage (0-100)
            width:
              type: number
              minimum: 0
              maximum: 100
              description: Width as percentage (0-100). x + width must be <= 100
            height:
              type: number
              minimum: 0
              maximum: 100
              description: Height as percentage (0-100). y + height must be <= 100
        page_number:
          type: integer
          minimum: 1
          description: >-
            Page number where field is located (1-indexed). Must not exceed the
            document's total page count.
        required:
          type: boolean
          default: false
          description: Whether field must be completed
        recipient_id:
          type: string
          description: >-
            ID of recipient assigned to this field. Use real UUID for
            template-based creation or updates, or temporary ID (e.g., 'temp_1')
            for document-based creation to reference recipients defined in the
            same request.
        variable_name:
          type: string
          maxLength: 100
          nullable: true
          description: >-
            Variable name for field (used in templates). Also used as fallback
            for field matching in template-based creation when template_field_id
            is not provided.
        variable_defined_name:
          type: string
          maxLength: 100
          nullable: true
          description: >-
            Human-readable custom field definition name. Can be used as an
            alternative to variable_name for targeting fields in template-based
            creation.
        dropdown_options:
          type: array
          items:
            type: string
          description: Options for dropdown fields
        date_default:
          type: string
          format: date
          nullable: true
          description: Default date value
        date_signing_default:
          type: boolean
          default: false
          description: Use signing date as default
        multi_group_id:
          type: string
          format: uuid
          nullable: true
          description: >-
            Group ID for linking multiple checkbox or radio button fields
            together. Fields sharing the same multi_group_id behave as a
            mutually exclusive group (like radio buttons) - selecting one
            automatically deselects the others in the group. Use the same UUID
            across multiple fields to create a group where only one option can
            be selected at a time.
        format_rules:
          oneOf:
            - $ref: '#/components/schemas/DateFormatRules'
            - $ref: '#/components/schemas/FileFormatRules'
            - type: object
              additionalProperties: true
          nullable: true
          description: >-
            Formatting rules for field value. For date fields, use
            DateFormatRules schema with dateFormat property. For file fields,
            use FileFormatRules schema with acceptedFileTypes property
            (image_and_pdf, image, or pdf). For url fields, use {
            urlDisplayText: string }.
        validation_rules:
          $ref: '#/components/schemas/FieldValidationRules'
        read_only:
          type: boolean
          default: false
          description: >-
            Whether this field is read-only (pre-filled before signing). When
            true, the signer cannot edit the field value. Useful for displaying
            contract terms, recipient information, or other fixed data.
        read_only_value:
          type: string
          nullable: true
          description: >-
            Static value for read-only fields. Takes precedence over
            prefilled_data if both are specified. Only applicable when read_only
            is true. Example: 'Contract #12345' or 'Acme Corporation'.
        prefilled_data:
          type: string
          nullable: true
          enum:
            - first_name
            - last_name
            - full_name
            - email
            - phone_number
            - company
            - title
            - street_address
            - city
            - state_province
            - postal_code
            - country
          description: >-
            User attribute to auto-populate when read_only is true. Value is
            pulled from the assigned recipient's data at signing time. Can also
            reference custom_fields keys defined on the recipient (not limited
            to enum values). Only applicable when read_only is true and
            read_only_value is not set. Example: Set to 'email' to display the
            recipient's email address.
        required_conditions:
          $ref: '#/components/schemas/ConditionSet'
          nullable: true
          description: >-
            Conditional rules for when this field is required. When set,
            overrides the static 'required' flag. The field is required only
            when the conditions evaluate to true based on other field values.
        visibility_conditions:
          $ref: '#/components/schemas/ConditionSet'
          nullable: true
          description: >-
            Conditional rules for when this field is visible. When set, the
            field is hidden unless the conditions evaluate to true. Hidden
            fields are not validated on submission.
        background_color:
          type: string
          nullable: true
          pattern: ^#([0-9A-Fa-f]{3}|[0-9A-Fa-f]{6})$
          description: >-
            Background color for the field as a hex color string (e.g.,
            '#FFFDE7', '#fff'). Useful for highlighting fields that need
            attention.
          example: '#FFFDE7'
    AnchorTag:
      type: object
      required:
        - anchor_string
        - type
        - recipient_id
      description: >-
        Anchor tag definition for automatic field placement. Anchor tags are
        text markers embedded in a PDF document (e.g., '{{SIGN_HERE}}') that are
        automatically located and converted into positioned fields. The anchor
        text is removed from the PDF after processing by default.
      properties:
        anchor_string:
          type: string
          minLength: 1
          maxLength: 200
          description: >-
            Text string to search for in the PDF document. Common patterns
            include '{{SIGN_HERE}}', '{{DATE}}', etc.
          example: '{{SIGN_HERE}}'
        type:
          type: string
          enum:
            - signature
            - initial
            - initials
            - text
            - date
            - checkbox
            - radio_buttons
            - radio
            - dropdown
            - textarea
            - text_area
            - url
            - approval_signature
            - approval_checkmark
            - approval_date
          description: Type of field to place at the anchor location
        recipient_id:
          oneOf:
            - type: integer
            - type: string
          description: >-
            ID of the recipient assigned to this field. Use temporary ID (e.g.,
            'temp_1') for document-based creation or integer order for
            template-based.
          example: temp_1
        x_offset:
          type: number
          description: >-
            Horizontal offset from anchor position. Units determined by
            offset_units (default: percent of page width).
          default: 0
        y_offset:
          type: number
          description: >-
            Vertical offset from anchor position. Units determined by
            offset_units (default: percent of page height).
          default: 0
        offset_units:
          type: string
          enum:
            - percent
            - pixels
          default: percent
          description: >-
            Unit type for x_offset and y_offset. 'percent' = percentage of page
            dimensions, 'pixels' = PDF points (72 DPI).
        width:
          type: number
          minimum: 0
          exclusiveMinimum: true
          description: >-
            Field width as percentage of page width. Defaults vary by field type
            (e.g., signature=25, text=20, checkbox=3).
        height:
          type: number
          minimum: 0
          exclusiveMinimum: true
          description: >-
            Field height as percentage of page height. Defaults vary by field
            type (e.g., signature=5, text=3, checkbox=3).
        case_sensitive:
          type: boolean
          default: false
          description: Whether anchor string matching is case-sensitive
        match_whole_word:
          type: boolean
          default: true
          description: Whether to match whole words only (bounded by non-word characters)
        ignore_if_not_present:
          type: boolean
          default: false
          description: >-
            If true, skip this anchor without error when not found in the
            document. If false (default), a missing anchor causes a validation
            error.
        occurrence:
          type: integer
          minimum: 0
          maximum: 1000
          default: 0
          description: >-
            Which occurrence to place a field on. 0 = all occurrences (default),
            1 = first only, 2 = second only, etc.
        remove_anchor_text:
          type: boolean
          default: true
          description: >-
            Whether to remove the anchor text from the PDF by drawing a white
            rectangle over it
        required:
          type: boolean
          default: true
          description: Whether the field must be completed by the signer
        read_only:
          type: boolean
          default: false
          description: Whether the field is read-only (pre-filled)
        read_only_value:
          type: string
          nullable: true
          maxLength: 10000
          description: Static value for read-only fields
        variable_name:
          type: string
          nullable: true
          maxLength: 255
          description: Variable name for the field
        variable_defined_name:
          type: string
          maxLength: 100
          nullable: true
          description: >-
            Human-readable custom field definition name. Can be used as an
            alternative to variable_name for targeting fields in template-based
            creation.
        background_color:
          type: string
          nullable: true
          pattern: ^#([0-9A-Fa-f]{3}|[0-9A-Fa-f]{6})$
          description: Background color as hex (e.g., '#FFFDE7')
          example: '#FFFDE7'
        dropdown_options:
          type: array
          items:
            type: string
          description: Options for dropdown fields
        date_default:
          type: string
          nullable: true
          maxLength: 50
          description: Default date value
        date_signing_default:
          type: boolean
          default: false
          description: Use signing date as default
        multi_group_id:
          type: string
          nullable: true
          maxLength: 255
          description: Group ID for linking checkbox/radio fields
    SigningRequestReminder:
      type: object
      required:
        - hours
        - subject
        - message
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier (include for updates, omit for new reminders)
        hours:
          type: integer
          minimum: 1
          description: Hours before expiration to send reminder
        all_users:
          type: boolean
          default: false
          description: Send reminder to all recipients
        recipient_id:
          type: string
          nullable: true
          description: >-
            Specific recipient ID (required if all_users is false). Use real
            UUID for existing recipients or temporary ID (e.g., 'temp_1') for
            document-based creation to reference recipients in the same request.
        subject:
          type: string
          maxLength: 255
          description: Email subject line
        message:
          type: string
          maxLength: 5000
          description: Email message body
    DateFormatRules:
      type: object
      description: >-
        Formatting rules for date fields. Specifies how date values should be
        displayed and formatted.
      properties:
        dateFormat:
          type: string
          description: >-
            Date format pattern. Use predefined formats or custom patterns with:
            yyyy (4-digit year), MM (2-digit month), dd (2-digit day), MMMM
            (full month name), MMM (abbreviated month name), HH (24-hour), mm
            (minute), ss (second). Examples: 'MM/dd/yyyy' displays as
            01/31/2024, 'MMMM dd, yyyy' displays as January 31, 2024.
          enum:
            - MM/dd/yyyy
            - dd/MM/yyyy
            - yyyy-MM-dd
            - MMMM dd, yyyy
            - MMM dd, yyyy
            - dd MMMM yyyy
          default: MM/dd/yyyy
      example:
        dateFormat: MMMM dd, yyyy
    FileFormatRules:
      type: object
      description: >-
        Formatting rules for file upload fields. Specifies which file types
        signers are allowed to upload.
      properties:
        acceptedFileTypes:
          type: string
          enum:
            - image_and_pdf
            - image
            - pdf
          default: image_and_pdf
          description: >-
            Accepted file types for upload. 'image_and_pdf' accepts JPG, PNG,
            and PDF. 'image' accepts JPG and PNG only. 'pdf' accepts PDF only.
            Files are validated by magic bytes, not just extension. Maximum file
            size is 10MB.
      example:
        acceptedFileTypes: image_and_pdf
    FieldValidationRules:
      type: object
      nullable: true
      description: >-
        Validation rules for field values. Reserved for future use - currently
        not enforced for any field types.
      additionalProperties: true
    ConditionSet:
      type: object
      required:
        - logic
        - groups
      description: >-
        A set of condition groups with nested logic. The outer 'logic' operator
        combines groups, while each group's conditions use the opposite
        operator. Example: logic='and' means all groups must match, and within
        each group any condition can match (OR).
      properties:
        logic:
          type: string
          enum:
            - and
            - or
          description: >-
            Logical operator to combine groups. 'and' = all groups must match,
            'or' = any group can match.
        groups:
          type: array
          items:
            $ref: '#/components/schemas/ConditionGroup'
          description: Array of condition groups
    ConditionGroup:
      type: object
      required:
        - conditions
      properties:
        conditions:
          type: array
          items:
            $ref: '#/components/schemas/Condition'
          description: >-
            Array of conditions within this group. Combined using the opposite
            of the parent ConditionSet's logic operator.
    Condition:
      type: object
      required:
        - field_id
        - operator
      description: A single condition that evaluates a field's value.
      properties:
        field_id:
          type: string
          format: uuid
          description: ID of the field to evaluate
        operator:
          type: string
          enum:
            - is_filled
            - is_empty
            - equals
            - not_equals
            - contains
            - not_contains
            - greater_than
            - less_than
            - greater_than_or_equal
            - less_than_or_equal
          description: >-
            Comparison operator. 'is_filled'/'is_empty' don't require a value.
            Text operators: equals, not_equals, contains, not_contains.
            Numeric/date operators: greater_than, less_than,
            greater_than_or_equal, less_than_or_equal.
        value:
          oneOf:
            - type: string
            - type: number
          nullable: true
          description: >-
            Value to compare against. Not required for is_filled/is_empty
            operators.
  responses:
    ValidationError:
      description: Bad Request - Validation failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Validation Error
            message: Invalid input data
            details:
              name: Name is required
              email: Invalid email format
    UnauthorizedError:
      description: Unauthorized - Invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Unauthorized
            message: Invalid API key
    RateLimitError:
      description: Too Many Requests - Rate limit exceeded
      headers:
        X-RateLimit-Limit:
          schema:
            type: integer
          description: Maximum requests per minute
        X-RateLimit-Remaining:
          schema:
            type: integer
          description: Requests remaining
        X-RateLimit-Reset:
          schema:
            type: integer
          description: Unix timestamp of reset
        Retry-After:
          schema:
            type: integer
          description: Seconds until retry allowed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Rate Limit Exceeded
            message: Too many requests. Please wait before retrying.
            details:
              retry_after: 45
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        API key for authentication. Use your API key directly without any prefix
        (e.g., 'your-api-key'). Bearer prefix is optional but not required.

````