> ## 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 and Send Signing Request (Atomic)

> Create and immediately send a signing request in a single atomic operation. This endpoint combines the functionality of POST /signing-requests and POST /signing-requests/{id}/send.

**Key Benefits:**
- Single API call instead of two separate requests
- Validates all send requirements BEFORE creating the signing request
- Atomic credit deduction - only charges if everything succeeds
- Returns status: 'sent' immediately with first signer details
- More efficient (saves 1 API call + round-trip time)

**Validation:**
- All standard creation validations (document/template, recipients, fields)
- Additional send validations:
  - All signers must have first_name and valid email
  - Required read-only fields must have final_value populated
  - Prefilled data fields (variable_name) must have corresponding user data
  - Company must have sufficient credits (≥1)

**Atomicity:**
- If any validation fails, nothing is created
- Credit is only deducted after successful creation and before email send
- If email send fails after creation, signing request remains in 'draft' status and credit is NOT deducted

**Temporary ID Pattern:** For document-based creation, use temporary IDs (format: 'temp_X') to reference recipients before creation. The API validates all references and automatically maps temporary IDs to real UUIDs.

**Rate Limit:** 120 requests/minute (same as write operations)



## OpenAPI

````yaml api-reference/v01.19.00/openapi-v01.19.00.json post /signing-requests/create-and-send
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.19.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/create-and-send:
    post:
      tags:
        - Signing Requests
      summary: Create and Send Signing Request (Atomic)
      description: >-
        Create and immediately send a signing request in a single atomic
        operation. This endpoint combines the functionality of POST
        /signing-requests and POST /signing-requests/{id}/send.


        **Key Benefits:**

        - Single API call instead of two separate requests

        - Validates all send requirements BEFORE creating the signing request

        - Atomic credit deduction - only charges if everything succeeds

        - Returns status: 'sent' immediately with first signer details

        - More efficient (saves 1 API call + round-trip time)


        **Validation:**

        - All standard creation validations (document/template, recipients,
        fields)

        - Additional send validations:
          - All signers must have first_name and valid email
          - Required read-only fields must have final_value populated
          - Prefilled data fields (variable_name) must have corresponding user data
          - Company must have sufficient credits (≥1)

        **Atomicity:**

        - If any validation fails, nothing is created

        - Credit is only deducted after successful creation and before email
        send

        - If email send fails after creation, signing request remains in 'draft'
        status and credit is NOT deducted


        **Temporary ID Pattern:** For document-based creation, use temporary IDs
        (format: 'temp_X') to reference recipients before creation. The API
        validates all references and automatically maps temporary IDs to real
        UUIDs.


        **Rate Limit:** 120 requests/minute (same as write operations)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                  maxLength: 255
                  description: Signing request name
                  example: Employment Contract - John Doe
                description:
                  type: string
                  description: Signing request description
                  example: Full-time employment contract for Software Engineer position
                document:
                  type: string
                  format: byte
                  description: >-
                    Base64-encoded PDF or DOCX document (mutually exclusive with
                    template_id). DOCX files are automatically converted to PDF.
                    Maximum size: 20MB.
                  example: >-
                    JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXBlIC9QYWdlCi9QYXJlbnQgMSAwIFIKL1Jlc291c...
                template_id:
                  type: string
                  format: uuid
                  description: Template ID to use (mutually exclusive with document)
                  example: 123e4567-e89b-12d3-a456-426614174000
                expiration_hours:
                  type: integer
                  minimum: 1
                  default: 168
                  description: 'Hours until signing request expires (default: 168 = 7 days)'
                  example: 168
                recipients:
                  type: array
                  description: >-
                    Array of recipients. At least one must be a Signer. For
                    document-based: required. For template-based: optional (uses
                    template recipients if omitted). Use template_user_id
                    (preferred) or order (fallback) to match template users.
                  minItems: 1
                  items:
                    $ref: '#/components/schemas/Recipient'
                fields:
                  type: array
                  description: Array of fields to be filled (document-based only)
                  items:
                    type: object
                    required:
                      - type
                      - page
                      - x
                      - 'y'
                    properties:
                      recipient_id:
                        type: string
                        description: >-
                          Temporary ID or UUID of recipient assigned to this
                          field
                        example: temp_signer_1
                      type:
                        type: string
                        enum:
                          - signature
                          - initial
                          - text
                          - date
                          - checkbox
                          - dropdown
                          - radio_buttons
                          - text_area
                          - url
                          - file
                          - stamp
                          - approval_signature
                          - approval_checkmark
                          - approval_date
                        description: >-
                          Field type. Accepts aliases: "initials" (normalized to
                          "initial"), "textarea" (normalized to "text_area"),
                          "radio" (normalized to "radio_buttons").
                        example: signature
                      page:
                        type: integer
                        minimum: 1
                        description: PDF page number (1-indexed)
                        example: 1
                      x:
                        type: number
                        description: X coordinate on page
                        example: 100
                      'y':
                        type: number
                        description: Y coordinate on page
                        example: 200
                      width:
                        type: number
                        default: 200
                        example: 200
                      height:
                        type: number
                        default: 50
                        example: 50
                      variable_name:
                        type: string
                        description: >-
                          Variable name for prefilled data (e.g.,
                          'phone_number', 'company'). If set, the corresponding
                          recipient field must be populated.
                        enum:
                          - first_name
                          - last_name
                          - full_name
                          - email
                          - phone_number
                          - street_address
                          - city
                          - state_province
                          - postal_code
                          - country
                          - title
                          - company
                        example: phone_number
                      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.
                      required:
                        type: boolean
                        default: false
                        description: Whether field is required
                      read_only:
                        type: boolean
                        default: false
                        description: Whether field is read-only (pre-filled)
                      final_value:
                        type: string
                        description: >-
                          Pre-filled value for read-only fields (required if
                          read_only=true and required=true)
                        example: Software Engineer
                      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. Required when type is
                          "dropdown".
                        example:
                          - Option A
                          - Option B
                          - Option C
                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
                  description: Array of reminder configurations
                  items:
                    type: object
                    required:
                      - hours_before_expiration
                    properties:
                      hours_before_expiration:
                        type: integer
                        minimum: 1
                        description: Hours before expiration to send reminder
                        example: 24
                settings:
                  type: object
                  description: Signing request settings
                  properties:
                    use_signing_order:
                      type: boolean
                      default: true
                      description: >-
                        Enforce signing order based on recipient.order. When
                        false, all signers receive the document simultaneously.
                    allow_download:
                      type: boolean
                      default: true
                      description: Allow recipients to download document
                    attach_pdf_on_finish:
                      type: boolean
                      default: true
                      description: Attach completed PDF to completion email
                    send_signing_email:
                      type: boolean
                      default: true
                      description: Send email notification to signers
                    send_finish_email:
                      type: boolean
                      default: true
                      description: Send email when all signatures complete
                    send_expiration_email:
                      type: boolean
                      default: true
                      description: Send email when request expires
                    send_cancellation_email:
                      type: boolean
                      default: true
                      description: Send email when request is cancelled
                    hand_drawn_only:
                      type: boolean
                      default: false
                      description: >-
                        Require signers to hand-draw their signatures instead of
                        using typed signatures
                    identity_editable_fields:
                      type: array
                      nullable: true
                      items:
                        type: string
                        enum:
                          - name
                          - company
                          - title
                          - phone
                          - address
                      description: >-
                        Identity fields signers can edit before signing. null =
                        disabled. When set, a confirmation dialog appears
                        allowing signers to edit the specified fields.
                      example:
                        - name
                        - company
                    notify_identity_change_webhook:
                      type: boolean
                      default: false
                      description: Send webhook event when a signer changes their identity
                    notify_identity_change_email:
                      type: boolean
                      default: false
                      description: >-
                        Send email notification when a signer changes their
                        identity
              oneOf:
                - required:
                    - document
                - required:
                    - template_id
            examples:
              document-based:
                summary: Create and send with document
                value:
                  name: Employment Contract - John Doe
                  description: Full-time employment contract
                  document: JVBERi0xLjQKJeLjz9MK...
                  expiration_hours: 168
                  recipients:
                    - id: temp_signer_1
                      first_name: John
                      last_name: Doe
                      email: john.doe@example.com
                      designation: Signer
                      order: 1
                      phone_number: +1-555-0123
                      company: Acme Corp
                      title: Software Engineer
                  fields:
                    - recipient_id: temp_signer_1
                      type: signature
                      page: 1
                      x: 100
                      'y': 500
                      width: 200
                      height: 50
                    - recipient_id: temp_signer_1
                      type: text
                      page: 1
                      x: 100
                      'y': 400
                      width: 150
                      height: 30
                      variable_name: phone_number
                      required: true
                      read_only: true
                  settings:
                    use_signing_order: true
                    send_signing_email: true
              template-based:
                summary: Create and send from template
                value:
                  name: NDA - Jane Smith
                  template_id: 123e4567-e89b-12d3-a456-426614174000
                  recipients:
                    - first_name: Jane
                      last_name: Smith
                      email: jane.smith@example.com
                      designation: Signer
                      order: 1
                      company: Tech Startup Inc
                  expiration_hours: 72
      responses:
        '201':
          description: Signing request created and sent successfully
          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:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                    description: Signing request ID
                  name:
                    type: string
                    description: Signing request name
                  description:
                    type: string
                    nullable: true
                    description: Signing request description
                  status:
                    type: string
                    enum:
                      - sent
                    description: Always 'sent' for this endpoint
                  document_url:
                    type: string
                    format: uri
                    description: Signed URL to access document
                  page_count:
                    type: integer
                    description: Number of pages in document
                  expiration_hours:
                    type: integer
                    description: Hours until expiration
                  settings:
                    $ref: '#/components/schemas/SigningRequestSettings'
                  created_date:
                    type: string
                    format: date-time
                  sent_date:
                    type: string
                    format: date-time
                    description: When request was sent
                  template_id:
                    type: string
                    format: uuid
                    nullable: true
                  first_signer:
                    type: object
                    description: Details of the first signer who received the email
                    properties:
                      id:
                        type: string
                        format: uuid
                      name:
                        type: string
                      email:
                        type: string
                        format: email
                      signing_link:
                        type: string
                        format: uri
                        description: Direct link for signer to access signing view
                  recipients:
                    type: array
                    description: All recipients with real UUIDs
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                        first_name:
                          type: string
                        last_name:
                          type: string
                          nullable: true
                        name:
                          type: string
                        email:
                          type: string
                          format: email
                        designation:
                          type: string
                        order:
                          type: integer
                  fields:
                    type: array
                    description: All fields with real recipient UUIDs
                    items:
                      $ref: '#/components/schemas/Field'
                  credits_remaining:
                    type: integer
                    description: Company credits remaining after deduction
              example:
                id: 550e8400-e29b-41d4-a716-446655440000
                name: Employment Contract - John Doe
                description: Full-time employment contract
                status: sent
                document_url: https://storage.supabase.co/...
                page_count: 3
                expiration_hours: 168
                settings:
                  use_signing_order: true
                  allow_download: true
                  attach_pdf_on_finish: true
                  send_signing_email: true
                  send_finish_email: true
                  send_expiration_email: true
                  send_cancellation_email: true
                  hand_drawn_only: false
                created_date: '2026-01-12T10:30:00Z'
                sent_date: '2026-01-12T10:30:00Z'
                template_id: null
                first_signer:
                  id: rec456-e89b-12d3-a456-426614174000
                  name: John Doe
                  email: john.doe@example.com
                  signing_link: >-
                    https://app.firma.dev/signing/rec456-e89b-12d3-a456-426614174000
                recipients:
                  - id: rec456-e89b-12d3-a456-426614174000
                    first_name: John
                    last_name: Doe
                    name: John Doe
                    email: john.doe@example.com
                    designation: Signer
                    order: 1
                fields:
                  - id: field123-e89b-12d3-a456-426614174000
                    type: signature
                    page: 1
                    x: 100
                    'y': 500
                    width: 200
                    height: 50
                    required: true
                    recipient_id: rec456-e89b-12d3-a456-426614174000
                credits_remaining: 99
        '400':
          description: Validation error - invalid input or missing required signer data
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  phase:
                    type: string
                    enum:
                      - create_validation
                      - send_validation
                    description: Which validation phase failed
                  validation_errors:
                    type: array
                    description: Detailed validation errors for send phase
                    items:
                      type: object
                      properties:
                        recipient_index:
                          type: integer
                          description: 1-based index of recipient
                        recipient_email:
                          type: string
                        missing_fields:
                          type: array
                          items:
                            type: string
                          description: List of missing required fields
              examples:
                missing-recipient-data:
                  value:
                    error: >-
                      One or more signers are missing required information for
                      sending
                    phase: send_validation
                    validation_errors:
                      - recipient_index: 1
                        recipient_email: john@example.com
                        missing_fields:
                          - phone_number
                          - company
                invalid-document:
                  value:
                    error: Document must be valid base64-encoded PDF
                    phase: create_validation
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '402':
          description: Insufficient credits
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: >-
                      Insufficient credits. Please purchase more credits to send
                      signing requests.
                  current_credits:
                    type: integer
                    example: 0
        '404':
          description: Template not found or does not belong to workspace
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/RateLimitError'
        '500':
          description: Server error - email send failed after creation
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: >-
                      Signing request created but email send failed. Please use
                      /send endpoint to retry.
                  signing_request_id:
                    type: string
                    format: uuid
                    description: ID of created signing request
                  send_error:
                    type: string
                    description: Details of email send failure
      security:
        - ApiKeyAuth: []
components:
  schemas:
    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
    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
    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
    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'
    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
    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:
    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.

````