{
    "openapi": "3.0.3",
    "info": {
      "title": "Firma Partner API",
      "description": "RESTful API for document signing and template management.\n\n**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.\n\n**Security Features**:\n- Input validation using Zod schemas with detailed field-level error messages\n- RSA-256 signed JWT tokens for embedded template access\n\n**Rate Limiting**: Rate limits are tiered based on operation type:\n- Read operations (GET): 200 requests per minute\n- Write operations (POST/PUT/PATCH/DELETE): 120 requests per minute\n- Webhook CRUD operations: 60 requests per minute\n- Webhook test: 10 requests per minute\n- API key regeneration/expiration: 1 request per minute\n- Webhook secret rotation: 1 request per minute\n\nWhen rate limits are exceeded, the API returns a `429 Too Many Requests` response with headers:\n- `X-RateLimit-Limit`: Maximum requests per minute for this endpoint\n- `X-RateLimit-Remaining`: Requests remaining in current window\n- `X-RateLimit-Reset`: Unix timestamp when limit resets\n- `Retry-After`: Seconds until retry is allowed\n\n**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).\n\n**Embedded Template Integration**: The Firma Template Editor can be embedded in your application using a standalone JavaScript library.\n\n```html\n<!-- Load the Firma Template Editor library -->\n<script src=\"https://api.firma.dev/functions/v1/embed-proxy/template-editor.js\"></script>\n\n<script>\n// Generate JWT token via API first\nfetch('https://api.firma.dev/functions/v1/signing-request-api/generate-template-token', {\n  method: 'POST',\n  headers: {\n    'Authorization': 'YOUR_API_KEY',\n    'Content-Type': 'application/json'\n  },\n  body: JSON.stringify({\n    companies_workspaces_templates_id: 'template-id'\n  })\n})\n.then(res => res.json())\n.then(data => {\n  // Initialize editor with JWT token\n  window.FirmaTemplateEditor.init({\n    container: '#firma-editor-container',\n    jwt: data.token,\n    templateId: 'template-id',\n    theme: 'dark',\n    readOnly: false,\n    onSave: (savedData) => {\n      console.log('Template saved:', savedData);\n    },\n    onError: (error) => {\n      console.error('Editor error:', error);\n    },\n    onLoad: (template) => {\n      console.log('Template loaded:', template);\n    }\n  });\n});\n```",
      "version": "01.10.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" }
    ],
    "components": {
      "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."
        }
      },
      "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"
              }
            }
          }
        },
        "ForbiddenError": {
          "description": "Forbidden - Insufficient permissions",
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/Error" },
              "example": {
                "error": "Forbidden",
                "message": "You do not have permission to access this resource"
              }
            }
          }
        },
        "NotFoundError": {
          "description": "Not Found - Resource does not exist",
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/Error" },
              "example": {
                "error": "Not Found",
                "message": "The requested resource was not found"
              }
            }
          }
        },
        "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
                }
              }
            }
          }
        }
      },
      "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"
                    }
                  }
                }
              }
            }
          }
        },
        "UpdateSigningRequestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateSigningRequestBodySchema"
              },
              "examples": {
                "comprehensive-update": {
                  "summary": "Comprehensive update with all sections",
                  "value": {
                    "signing_request_properties": {
                      "name": "Updated Contract Name",
                      "expiration_hours": 72
                    },
                    "recipients": [
                      {
                        "id": "rec1-e89b-12d3-a456-426614174000",
                        "first_name": "John",
                        "last_name": "Smith",
                        "email": "john.smith@example.com",
                        "designation": "Signer",
                        "order": 1
                      },
                      {
                        "first_name": "Jane",
                        "last_name": "Doe",
                        "email": "jane@example.com",
                        "designation": "Signer",
                        "order": 2
                      }
                    ],
                    "deleted_recipients": [
                      {
                        "recipient_id": "rec2-e89b-12d3-a456-426614174000",
                        "field_action": "reassign",
                        "reassign_to_recipient_id": "rec1-e89b-12d3-a456-426614174000"
                      }
                    ],
                    "fields": [
                      {
                        "id": "field1-e89b-12d3-a456-426614174000",
                        "type": "signature",
                        "position": { "x": 15, "y": 85, "width": 30, "height": 10 },
                        "page_number": 1,
                        "required": true,
                        "recipient_id": "rec1-e89b-12d3-a456-426614174000"
                      }
                    ],
                    "reminders": [
                      {
                        "hours": 48,
                        "all_users": true,
                        "subject": "Reminder: Please sign the document",
                        "message": "This is a reminder to complete your signature."
                      }
                    ]
                  }
                },
                "update-with-temp-ids": {
                  "summary": "Update with new recipients using temporary IDs",
                  "description": "Comprehensive update adding new recipients with temporary IDs alongside existing recipients",
                  "value": {
                    "signing_request_properties": {
                      "name": "Updated NDA Agreement"
                    },
                    "recipients": [
                      {
                        "id": "existing-recipient-uuid",
                        "email": "updated@example.com"
                      },
                      {
                        "_temp_id": "temp_new_signer",
                        "first_name": "New",
                        "last_name": "Signer",
                        "email": "newsigner@example.com",
                        "designation": "Signer",
                        "order": 2
                      }
                    ],
                    "fields": [
                      {
                        "id": "existing-field-uuid",
                        "position": { "x": 10, "y": 70, "width": 30, "height": 10 }
                      },
                      {
                        "recipient_id": "temp_new_signer",
                        "type": "signature",
                        "page_number": 1,
                        "position": { "x": 10, "y": 55, "width": 30, "height": 10 },
                        "required": true
                      }
                    ],
                    "reminders": [
                      {
                        "recipient_id": "temp_new_signer",
                        "hours": 24,
                        "all_users": false,
                        "subject": "Reminder: Sign Document",
                        "message": "Please sign the updated NDA."
                      }
                    ]
                  }
                }
              }
            }
          }
        }
      },
      "schemas": {
        "Company": {
          "type": "object",
          "properties": {
            "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the company" },
            "name": { "type": "string", "description": "Company name", "maxLength": 255 },
            "language": { "type": "string", "description": "Default language for the company", "enum": ["en", "es", "it", "pt", "fr", "de", "el"], "default": "en" },
            "account_owner": { "type": "string", "description": "Name of the account owner", "maxLength": 255 },
            "account_owner_email": { "type": "string", "format": "email", "description": "Email address of the account owner" },
            "website": { "type": "string", "format": "uri", "description": "Company website URL", "nullable": true },
            "icon_url": { "type": "string", "format": "uri", "description": "URL to company icon/logo", "nullable": true },
            "credits": { "type": "integer", "description": "Available credits for the company (read-only, managed internally)", "minimum": 0, "readOnly": true },
            "created_date": { "type": "string", "format": "date-time", "description": "Company account creation timestamp" },
            "updated_date": { "type": "string", "format": "date-time", "description": "Company account last update timestamp" }
          }
        },
        "Workspace": {
          "type": "object",
          "properties": {
            "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the workspace" },
            "name": { "type": "string", "description": "Workspace name", "maxLength": 255 },
            "protected": { "type": "boolean", "description": "Protected workspaces cannot be deleted" },
            "api_key": { "type": "string", "description": "Unique API key for this workspace. Used for authenticating API requests scoped to this workspace.", "nullable": true },
            "created_date": { "type": "string", "format": "date-time", "description": "Workspace creation timestamp" },
            "updated_date": { "type": "string", "format": "date-time", "description": "Workspace last update timestamp" }
          }
        },
        "Template": {
          "type": "object",
          "properties": {
            "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the template" },
            "name": { "type": "string", "description": "Template name", "maxLength": 255 },
            "description": { "type": "string", "description": "Template description", "nullable": true },
            "document_url": { "type": "string", "format": "uri", "description": "Pre-signed URL to the PDF document. This is a time-limited signed URL for secure access - see document_url_expires_at for expiration time. Initial URLs are valid for 7 days; refreshed URLs are valid for 1 hour. Request a new template retrieval to get a fresh URL if expired." },
            "document_url_expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "ISO 8601 timestamp when the document_url will expire. After this time, the URL will return an access denied error. Fetch the template again to receive a fresh signed URL." },
            "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 requests created from this template expire" },
            "credit_cost": { "type": "integer", "minimum": 1, "default": 1, "description": "Number of credits consumed when a signing request is sent from this template. Minimum value is 1." },
            "settings": { "$ref": "#/components/schemas/SigningRequestSettings" },
            "recipients": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateUser" }, "description": "Template recipients (included in GET single template)" },
            "fields": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateField" }, "description": "Template fields (included in GET single template)" },
            "created_date": { "type": "string", "format": "date-time", "description": "Template creation timestamp" },
            "updated_date": { "type": "string", "format": "date-time", "description": "Template last update timestamp" }
          }
        },
        "TemplateUser": {
          "type": "object",
          "properties": {
            "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the template user" },
            "name": { "type": "string", "description": "Recipient name (combined first and last name)" },
            "email": { "type": "string", "format": "email", "description": "Recipient email address" },
            "first_name": { "type": "string", "nullable": true, "description": "Recipient first name" },
            "last_name": { "type": "string", "nullable": true, "description": "Recipient last name" },
            "designation": { "type": "string", "enum": ["Signer"], "description": "Role of the recipient" },
            "order": { "type": "integer", "minimum": 1, "description": "Order in which the recipient should sign" },
            "phone_number": { "type": "string", "nullable": true, "description": "Recipient phone number" },
            "street_address": { "type": "string", "nullable": true, "description": "Recipient street address" },
            "city": { "type": "string", "nullable": true, "description": "Recipient city" },
            "state_province": { "type": "string", "nullable": true, "description": "Recipient state or province" },
            "postal_code": { "type": "string", "nullable": true, "description": "Recipient postal code" },
            "country": { "type": "string", "nullable": true, "description": "Recipient country" },
            "title": { "type": "string", "nullable": true, "description": "Recipient job title" },
            "company": { "type": "string", "nullable": true, "description": "Recipient company name" },
            "required_fields": { 
              "type": "array", 
              "items": { "type": "string" }, 
              "description": "List of recipient data fields required for sending (based on template fields with variable_name mappings). Always includes 'email' and 'first_name'." 
            },
            "missing_fields": { 
              "type": "array", 
              "items": { "type": "string" }, 
              "description": "List of required fields that are currently empty for this recipient" 
            },
            "required_read_only_fields": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "variable_name": { "type": "string", "nullable": true, "description": "Variable name of the read-only field" },
                  "field_type": { "type": "string", "description": "Type of the field (text, date, etc.)" }
                }
              },
              "description": "List of required read-only fields that need pre-filled values before sending"
            },
            "ready_to_send": { 
              "type": "boolean", 
              "description": "Whether this recipient has all required data filled in for sending" 
            }
          }
        },
        "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"
          }
        },
        "FieldValidationRules": {
          "type": "object",
          "nullable": true,
          "description": "Validation rules for field values. Reserved for future use - currently not enforced for any field types.",
          "additionalProperties": true
        },
        "TemplateField": {
          "type": "object",
          "description": "A field placed on a template document",
          "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"], "description": "Type of the field" },
            "required": { "type": "boolean", "description": "Whether the field is required" },
            "recipient_id": { "type": "string", "format": "uuid", "nullable": true, "description": "ID of assigned recipient" },
            "variable_name": { "type": "string", "nullable": true, "description": "Variable name for field (used in templates)" },
            "position": {
              "type": "object",
              "description": "Position and dimensions of the field on the document. All values are percentages (0-100). The field must fit within the page: x + width <= 100 and y + height <= 100.",
              "properties": {
                "x": { "type": "number", "minimum": 0, "maximum": 100, "description": "X coordinate of field position (percentage, 0-100)" },
                "y": { "type": "number", "minimum": 0, "maximum": 100, "description": "Y coordinate of field position (percentage, 0-100)" },
                "width": { "type": "number", "minimum": 0, "maximum": 100, "description": "Width of the field (percentage, 0-100). Note: x + width must be <= 100" },
                "height": { "type": "number", "minimum": 0, "maximum": 100, "description": "Height of the field (percentage, 0-100). Note: y + height must be <= 100" }
              }
            },
            "page_number": { "type": "integer", "minimum": 1, "nullable": true, "description": "Page number where the field is located (1-indexed). Must not exceed the document's total page count." },
            "dropdown_options": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "Options for dropdown fields" },
            "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." },
            "date_default": { "type": "string", "format": "date", "nullable": true, "description": "Default date value for date fields (ISO 8601 format, e.g., '2024-01-15')" },
            "date_signing_default": { "type": "boolean", "description": "Use signing date as default for date fields" },
            "format_rules": { "$ref": "#/components/schemas/DateFormatRules", "nullable": true, "description": "Formatting rules - currently used for date fields to specify display format" },
            "validation_rules": { "$ref": "#/components/schemas/FieldValidationRules" },
            "read_only": { "type": "boolean", "default": false, "description": "Whether this field is read-only (pre-filled before signing)" },
            "read_only_value": { "type": "string", "nullable": true, "description": "Static value for read-only fields" }
          }
        },
        "Reminder": {
          "type": "object",
          "properties": {
            "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the reminder" },
            "hours": { "type": "integer", "minimum": 1, "description": "Hours after sending before reminder is sent" },
            "subject": { "type": "string", "description": "Email subject for the reminder", "maxLength": 255 },
            "message": { "type": "string", "description": "Email message body for the reminder", "maxLength": 5000 },
            "all_users": { "type": "boolean", "description": "Whether reminder applies to all users" },
            "template_user_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Specific user to send reminder to (used in template context)" },
            "recipient_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Specific recipient to send reminder to (used in signing request context, same as template_user_id)" },
            "sent_on": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp when the reminder was actually sent" },
            "created_at": { "type": "string", "format": "date-time", "description": "Reminder creation timestamp" },
            "updated_at": { "type": "string", "format": "date-time", "description": "Reminder last update timestamp" }
          }
        },
        "SigningRequestListItem": {
          "type": "object",
          "description": "Signing request as returned by the LIST endpoint (GET /signing-requests)",
          "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": ["not_sent", "in_progress", "finished", "cancelled", "declined", "deleted", "expired"], "description": "Current status of the signing request" },
            "document_url": { "type": "string", "format": "uri", "description": "Pre-signed URL to the PDF document. This is a time-limited signed URL for secure access - see document_url_expires_at for expiration time. Initial URLs are valid for 7 days; refreshed URLs are valid for 1 hour. Request a new signing request retrieval to get a fresh URL if expired." },
            "document_url_expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "ISO 8601 timestamp when the document_url will expire. After this time, the URL will return an access denied error. Fetch the signing request again to receive a fresh signed URL." },
            "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)" },
            "expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "ISO 8601 timestamp when the signing request expires. Computed from sent_date + expiration_hours. Null if the signing request has not been sent yet or has no expiration_hours set." },
            "credit_cost": { "type": "integer", "minimum": 1, "default": 1, "description": "Number of credits consumed when this signing request was sent. Minimum value is 1." },
            "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" },
            "declined_date": { "type": "string", "format": "date-time", "nullable": true, "description": "When the signing request was declined" },
            "recipients": {
              "type": "array",
              "description": "Signing request recipients (simplified shape)",
              "items": { "$ref": "#/components/schemas/SigningRequestListRecipient" }
            },
            "fields": {
              "type": "array",
              "description": "Signing request fields with nested position object",
              "items": {
                "type": "object",
                "properties": {
                  "id": { "type": "string", "format": "uuid" },
                  "type": { "type": "string", "enum": ["text", "signature", "date", "checkbox", "dropdown", "radio_buttons", "number", "text_area", "file", "initial"] },
                  "required": { "type": "boolean" },
                  "recipient_id": { "type": "string", "format": "uuid", "nullable": true },
                  "variable_name": { "type": "string", "nullable": true },
                  "position": {
                    "type": "object",
                    "properties": {
                      "x": { "type": "number" },
                      "y": { "type": "number" },
                      "width": { "type": "number" },
                      "height": { "type": "number" }
                    }
                  },
                  "value": { "type": "string", "nullable": true, "description": "Final value of the field after signing" },
                  "dropdown_options": { "type": "array", "items": { "type": "string" }, "nullable": true },
                  "format_rules": { "$ref": "#/components/schemas/DateFormatRules", "nullable": true },
                  "validation_rules": { "$ref": "#/components/schemas/FieldValidationRules" }
                }
              }
            }
          }
        },
        "SigningRequestListRecipient": {
          "type": "object",
          "description": "Recipient as returned in LIST signing request responses (simplified shape)",
          "properties": {
            "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the recipient" },
            "name": { "type": "string", "description": "Combined full name" },
            "email": { "type": "string", "format": "email", "description": "Recipient email address" },
            "designation": { "type": "string", "enum": ["Signer"], "description": "Role of the recipient" },
            "order": { "type": "integer", "minimum": 1, "description": "Signing order" },
            "finished_date": { "type": "string", "format": "date-time", "nullable": true, "description": "When this recipient completed signing" },
            "signature_details": { "type": "object", "nullable": true, "description": "Details about the recipient's signature" }
          }
        },
        "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." }
          }
        },
        "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"], "description": "Role of the recipient" },
            "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"], "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" },
            "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" }
          }
        },
        "SigningRequestDetail": {
          "type": "object",
          "description": "Detailed signing request as returned by GET /signing-requests/{id} (nested shape with status object and timestamps)",
          "properties": {
            "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the signing request" },
            "name": { "type": "string", "description": "Signing request name" },
            "template_description": { "type": "string", "nullable": true, "description": "Description from the template" },
            "companies_workspaces_id": { "type": "string", "format": "uuid", "description": "Workspace ID this signing request belongs to" },
            "document_url": { "type": "string", "format": "uri", "description": "Pre-signed URL to the PDF document" },
            "document_url_expires_at": { "type": "string", "format": "date-time", "nullable": true },
            "document_page_count": { "type": "integer", "minimum": 1, "description": "Number of pages in the document" },
            "expiration_hours": { "type": "integer", "description": "Hours until signing request expires" },
            "expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "ISO 8601 timestamp when the signing request expires. Computed from sent_on + expiration_hours. Null if not sent yet or no expiration_hours set." },
            "credit_cost": { "type": "integer", "description": "Credits consumed when sent" },
            "status": {
              "type": "object",
              "description": "Status flags (multiple can be true for terminal states)",
              "properties": {
                "sent": { "type": "boolean" },
                "finished": { "type": "boolean" },
                "cancelled": { "type": "boolean" },
                "declined": { "type": "boolean" },
                "expired": { "type": "boolean" }
              }
            },
            "timestamps": {
              "type": "object",
              "description": "All relevant timestamps for the signing request lifecycle",
              "properties": {
                "created_on": { "type": "string", "format": "date-time" },
                "sent_on": { "type": "string", "format": "date-time", "nullable": true },
                "finished_on": { "type": "string", "format": "date-time", "nullable": true },
                "cancelled_on": { "type": "string", "format": "date-time", "nullable": true },
                "declined_on": { "type": "string", "format": "date-time", "nullable": true },
                "last_changed_on": { "type": "string", "format": "date-time" },
                "last_signing_action_on": { "type": "string", "format": "date-time", "nullable": true }
              }
            },
            "settings": { "$ref": "#/components/schemas/SigningRequestSettings" },
            "use_signing_order": { "type": "integer", "enum": [0, 1], "deprecated": true },
            "allow_download": { "type": "integer", "enum": [0, 1], "deprecated": true },
            "allow_editing_before_sending": { "type": "integer", "enum": [0, 1], "deprecated": true },
            "hand_drawn_only": { "type": "integer", "enum": [0, 1], "deprecated": true },
            "attach_pdf_on_finish": { "type": "integer", "enum": [0, 1], "deprecated": true },
            "certificate": {
              "type": "object",
              "nullable": true,
              "description": "Certificate generation status information",
              "properties": {
                "generated": { "type": "boolean", "description": "Whether the final certificate PDF has been generated" },
                "generated_on": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp when certificate was generated" },
                "has_error": { "type": "boolean", "description": "Whether there was an error generating the certificate" }
              }
            },
            "final_document_download_url": { "type": "string", "format": "uri", "nullable": true, "description": "Signed URL to download the final signed document (PDF with certificate). URL expires after 1 hour." },
            "final_document_download_error": { "type": "string", "nullable": true, "enum": ["file_not_accessible", null] },
            "document_only_download_url": { "type": "string", "format": "uri", "nullable": true, "description": "Signed URL to download the document-only PDF. URL expires after 1 hour." },
            "document_only_download_error": { "type": "string", "nullable": true, "enum": ["file_not_accessible", null] },
            "certificate_only_download_url": { "type": "string", "format": "uri", "nullable": true, "description": "Signed URL to download the certificate-only PDF. URL expires after 1 hour." },
            "certificate_only_download_error": { "type": "string", "nullable": true, "enum": ["file_not_accessible", null] }
          }
        },
        "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", "default": false },
            "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 }
          }
        },
        "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.",
          "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"], "description": "Role of the recipient" },
            "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"], "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." },
            "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" },
                { "type": "object", "additionalProperties": true }
              ],
              "nullable": true,
              "description": "Formatting rules for field value. For date fields, use DateFormatRules schema with dateFormat property. Predefined formats: MM/dd/yyyy, dd/MM/yyyy, yyyy-MM-dd, MMMM dd yyyy, MMM dd yyyy, dd MMMM yyyy. Custom formats supported using yyyy (year), MM (month), dd (day), MMMM (full month name), MMM (abbreviated month), HH (hour), mm (minute), ss (second)."
            },
            "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." }
          }
        },
        "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." }
          }
        },
        "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" }
          }
        },
        "DeletedRecipient": {
          "type": "object",
          "required": ["recipient_id", "field_action"],
          "properties": {
            "recipient_id": { "type": "string", "format": "uuid", "description": "ID of recipient to delete" },
            "field_action": { "type": "string", "enum": ["delete", "reassign"], "description": "Action to take with fields assigned to this recipient" },
            "reassign_to_recipient_id": { "type": "string", "format": "uuid", "description": "Recipient to reassign fields to (required if field_action is 'reassign')" }
          }
        },
        "SigningRequestUser": {
          "type": "object",
          "properties": {
            "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the signing request user" },
            "name": { "type": "string", "description": "Recipient name (combined first and last name)" },
            "email": { "type": "string", "format": "email", "description": "Recipient email address" },
            "first_name": { "type": "string", "nullable": true, "description": "Recipient first name" },
            "last_name": { "type": "string", "nullable": true, "description": "Recipient last name" },
            "designation": { "type": "string", "enum": ["Signer"], "description": "Role of the recipient" },
            "order": { "type": "integer", "minimum": 1, "description": "Signing order" },
            "finished_on": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp when this recipient completed all actions" },
            "declined_on": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp when this recipient declined to sign" },
            "decline_reason": { "type": "string", "nullable": true, "description": "Reason provided by recipient for declining" },
            "phone_number": { "type": "string", "nullable": true, "description": "Recipient phone number" },
            "street_address": { "type": "string", "nullable": true, "description": "Recipient street address" },
            "city": { "type": "string", "nullable": true, "description": "Recipient city" },
            "state_province": { "type": "string", "nullable": true, "description": "Recipient state or province" },
            "postal_code": { "type": "string", "nullable": true, "description": "Recipient postal code" },
            "country": { "type": "string", "nullable": true, "description": "Recipient country" },
            "title": { "type": "string", "nullable": true, "description": "Recipient job title" },
            "company": { "type": "string", "nullable": true, "description": "Recipient company name" },
            "custom_fields": { "type": "object", "nullable": true, "description": "Custom field values for this recipient" },
            "required_fields": { 
              "type": "array", 
              "items": { "type": "string" }, 
              "description": "List of recipient data fields required for sending (based on fields with variable_name mappings). Always includes 'email' and 'first_name'." 
            },
            "missing_fields": { 
              "type": "array", 
              "items": { "type": "string" }, 
              "description": "List of required fields that are currently empty for this recipient" 
            },
            "required_read_only_fields": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "variable_name": { "type": "string", "nullable": true, "description": "Variable name of the read-only field" },
                  "field_type": { "type": "string", "description": "Type of the field (text, date, etc.)" },
                  "has_value": { "type": "boolean", "description": "Whether this read-only field has a value set" }
                }
              },
              "description": "List of required read-only fields that need pre-filled values before sending"
            },
            "ready_to_send": { 
              "type": "boolean", 
              "description": "Whether this recipient has all required data filled in for sending" 
            }
          }
        },
        "SigningRequestField": {
          "type": "object",
          "description": "Field associated with a signing request, containing position, type, and value information",
          "properties": {
            "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the field" },
            "companies_workspaces_signing_requests_id": { "type": "string", "format": "uuid", "description": "ID of the signing request this field belongs to" },
            "companies_workspaces_signing_requests_users_id": { "type": "string", "format": "uuid", "nullable": true, "description": "ID of the recipient assigned to this field" },
            "field_type": { "type": "string", "enum": ["text", "signature", "date", "checkbox", "initial", "dropdown", "radio_buttons", "text_area", "url"], "description": "Type of the field. url fields are read-only and display a clickable link." },
            "required": { "type": "integer", "enum": [0, 1], "description": "Whether the field is required (0 = no, 1 = yes)" },
            "x_postion": { "type": "number", "nullable": true, "description": "X position of the field on the document (note: column name has typo)" },
            "y_position": { "type": "number", "nullable": true, "description": "Y position of the field on the document" },
            "width": { "type": "number", "nullable": true, "description": "Width of the field" },
            "heigh": { "type": "number", "nullable": true, "description": "Height of the field (note: column name has typo)" },
            "page_number": { "type": "integer", "nullable": true, "description": "Page number where the field is located (1-indexed)" },
            "tl_position": { "type": "number", "nullable": true, "description": "Top-left corner position" },
            "tr_position": { "type": "number", "nullable": true, "description": "Top-right corner position" },
            "bl_position": { "type": "number", "nullable": true, "description": "Bottom-left corner position" },
            "br_position": { "type": "number", "nullable": true, "description": "Bottom-right corner position" },
            "variable_name": { "type": "string", "nullable": true, "description": "Variable name for prefilled data mapping" },
            "final_value": { "type": "string", "nullable": true, "description": "Final signed value of the field" },
            "date_default": { "type": "string", "nullable": true, "description": "Default date value" },
            "date_signing_default": { "type": "integer", "enum": [0, 1], "nullable": true, "description": "Whether to use signing date as default (0 = no, 1 = yes)" },
            "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" },
            "dropdown_options": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "Options for dropdown fields" },
            "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." },
            "read_only": { "type": "integer", "enum": [0, 1], "description": "Whether the field is read-only (0 = no, 1 = yes)" },
            "read_only_value": { "type": "string", "nullable": true, "description": "Static value for read-only fields" },
            "calculated_font_size": { "type": "number", "nullable": true, "description": "Calculated font size for the field" },
            "deleted": { "type": "integer", "enum": [0, 1], "description": "Soft delete flag (0 = active, 1 = deleted)" }
          }
        },
        "SendSigningRequestResponse": {
          "type": "object",
          "properties": {
            "success": { "type": "boolean", "description": "Whether the signing request was sent successfully" },
            "message": { "type": "string", "description": "Success message" },
            "sentTo": { "type": "string", "format": "email", "description": "Email address the signing request was sent to" },
            "sentAt": { "type": "string", "format": "date-time", "description": "Timestamp when the request was sent" }
          }
        },
        "Webhook": {
          "type": "object",
          "properties": {
            "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the webhook" },
            "url": { "type": "string", "format": "uri", "description": "Webhook URL" },
            "description": { "type": "string", "nullable": true, "description": "Webhook description" },
            "events": { "type": "array", "items": { "type": "string" }, "description": "Events that trigger this webhook" },
            "enabled": { "type": "boolean", "description": "Whether the webhook is enabled" },
            "consecutive_failures": { "type": "integer", "description": "Number of consecutive delivery failures" },
            "auto_disabled_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp when the webhook was auto-disabled due to failures" },
            "created_at": { "type": "string", "format": "date-time", "description": "Webhook creation timestamp" },
            "updated_at": { "type": "string", "format": "date-time", "description": "Webhook last update timestamp" }
          }
        },
        "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." 
                },
                "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"
                  }
                ]
              }
            }
          ]
        },
        "UpdateSigningRequestBodySchema": {
          "type": "object",
          "properties": {
            "signing_request_properties": {
              "type": "object",
              "description": "Update signing request properties",
              "properties": {
                "name": { "type": "string", "maxLength": 255 },
                "description": { "type": "string" },
                "document": { "type": "string", "format": "byte", "description": "Replace document (base64-encoded PDF)" },
                "expiration_hours": { "type": "integer", "minimum": 1 },
                "settings": { "$ref": "#/components/schemas/SigningRequestSettings" }
              }
            },
            "recipients": { "type": "array", "items": { "$ref": "#/components/schemas/Recipient" }, "description": "Upsert recipients - include 'id' to update existing recipients, use '_temp_id' (e.g., 'temp_1') for new recipients to reference them in fields and reminders within the same request" },
            "deleted_recipients": { "type": "array", "items": { "$ref": "#/components/schemas/DeletedRecipient" }, "description": "Recipients to delete and how to handle their fields" },
            "force_remove_conditions": { "type": "boolean", "default": false, "description": "When deleting recipients whose fields are referenced by conditions in other fields: if true, automatically remove the condition references; if false (default), the request will be rejected with an error listing the dependent fields." },
            "fields": { "type": "array", "items": { "$ref": "#/components/schemas/Field" }, "description": "Upsert fields - include id to update, omit id to create new" },
            "reminders": { "type": "array", "items": { "$ref": "#/components/schemas/SigningRequestReminder" }, "description": "Upsert reminders - include id to update, omit id to create new" }
          }
        },
        "GenerateJWTRequest": {
          "type": "object",
          "required": ["companies_workspaces_templates_id"],
          "properties": {
            "companies_workspaces_templates_id": { "type": "string", "format": "uuid", "description": "ID of the template to generate JWT for" }
          }
        },
        "GenerateJWTResponse": {
          "type": "object",
          "properties": {
            "token": { "type": "string", "description": "The generated JWT token" },
            "jwt_record_id": { "type": "string", "format": "uuid", "description": "Unique identifier for this JWT record" },
            "expires_at": { "type": "string", "format": "date-time", "description": "JWT expiration timestamp (30 days from creation)" }
          }
        },
        "RevokeJWTRequest": {
          "type": "object",
          "required": ["jwt_id"],
          "properties": {
            "jwt_id": { "type": "string", "format": "uuid", "description": "ID of the JWT token to revoke" }
          }
        },
        "RevokeJWTResponse": {
          "type": "object",
          "properties": {
            "message": { "type": "string", "description": "Confirmation message" },
            "jwt_id": { "type": "string", "format": "uuid", "description": "ID of the revoked JWT" },
            "revoked": { "type": "boolean", "description": "Whether the JWT was successfully revoked" }
          }
        },
        "GenerateSigningRequestJWTRequest": {
          "type": "object",
          "required": ["companies_workspaces_signing_requests_id"],
          "properties": {
            "companies_workspaces_signing_requests_id": { "type": "string", "format": "uuid", "description": "ID of the signing request to generate JWT for" }
          }
        },
        "GenerateSigningRequestJWTResponse": {
          "type": "object",
          "properties": {
            "jwt": { "type": "string", "description": "The generated JWT token" },
            "jwt_id": { "type": "string", "format": "uuid", "description": "Unique identifier for this JWT" },
            "expires_at": { "type": "string", "format": "date-time", "description": "JWT expiration timestamp (7 days from creation)" },
            "signing_request_id": { "type": "string", "format": "uuid", "description": "ID of the signing request this JWT is for" },
            "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the JWT was created" }
          }
        },
        "RevokeSigningRequestJWTRequest": {
          "type": "object",
          "required": ["jwt_id"],
          "properties": {
            "jwt_id": { "type": "string", "format": "uuid", "description": "ID of the JWT token to revoke" }
          }
        },
        "RevokeSigningRequestJWTResponse": {
          "type": "object",
          "properties": {
            "message": { "type": "string", "description": "Confirmation message" },
            "jwt_id": { "type": "string", "format": "uuid", "description": "ID of the revoked JWT" },
            "revoked": { "type": "boolean", "description": "Whether the JWT was successfully revoked" }
          }
        },
        "WorkspaceSettings": {
          "type": "object",
          "properties": {
            "workspace_id": { "type": "string", "format": "uuid" },
            "name": { "type": "string", "description": "Workspace name" },
            "team_email": { "type": "string", "format": "email", "description": "Workspace contact email" },
            "timezone": { "type": "string", "description": "Workspace timezone" },
            "language": { "type": "string", "description": "Workspace language for email templates", "enum": ["en", "es", "it", "pt", "fr", "de", "el"], "default": "en" },
            "signing_request_email_header": { "type": "string", "description": "Custom email header text" },
            "signing_request_email_body": { "type": "string", "description": "Custom HTML email body" },
            "show_credit_cost_in_editor": { "type": "boolean", "description": "Whether to display credit cost in embedded template and signing request editors", "default": true },
            "require_otp_verification": { "type": "boolean", "nullable": true, "description": "Whether signers must verify their email via OTP before accessing documents. null = inherit from company setting, true = require OTP, false = do not require OTP" },
            "show_signature_frame": { "type": "boolean", "nullable": true, "description": "Whether to render a visual frame with Signature ID around signatures in completed PDFs. null = inherit from company setting (default enabled), true = show frame, false = hide frame" }
          }
        },
        "WorkspaceCustomField": {
          "type": "object",
          "description": "A custom field definition for a workspace",
          "properties": {
            "id": { "type": "string", "format": "uuid", "description": "Unique identifier" },
            "field_name": { "type": "string", "description": "Machine-readable field name (auto-generated from label)" },
            "field_label": { "type": "string", "description": "Human-readable display label" },
            "is_preset": { "type": "boolean", "description": "If true, this field has a preset value for all users" },
            "preset_value": { "type": "string", "nullable": true, "description": "Preset value (only used when is_preset=true)" },
            "created_at": { "type": "string", "format": "date-time" },
            "updated_at": { "type": "string", "format": "date-time" }
          }
        },
        "TemplateCustomField": {
          "type": "object",
          "description": "A custom field definition for a template",
          "properties": {
            "id": { "type": "string", "format": "uuid", "description": "Unique identifier" },
            "field_name": { "type": "string", "description": "Machine-readable field name" },
            "field_label": { "type": "string", "description": "Human-readable display label" },
            "created_at": { "type": "string", "format": "date-time" },
            "updated_at": { "type": "string", "format": "date-time" }
          }
        },
        "SigningRequestCustomField": {
          "type": "object",
          "description": "A custom field definition for a signing request",
          "properties": {
            "id": { "type": "string", "format": "uuid", "description": "Unique identifier" },
            "field_name": { "type": "string", "description": "Machine-readable field name" },
            "field_label": { "type": "string", "description": "Human-readable display label" },
            "copied_from_template": { "type": "boolean", "description": "True if this field was copied from a template" },
            "created_at": { "type": "string", "format": "date-time" },
            "updated_at": { "type": "string", "format": "date-time" }
          }
        },
        "Domain": {
          "type": "object",
          "description": "Email domain configuration for sending signing request emails",
          "properties": {
            "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the domain" },
            "domain": { "type": "string", "description": "The domain name (e.g., 'example.com')" },
            "verification_status": { 
              "type": "integer", 
              "enum": [0, 1, 2],
              "description": "Domain ownership verification status: 0=pending, 1=ownership verified (TXT record confirmed), 2=finalized (registered with email provider)" 
            },
            "domain_status": { 
              "type": "integer", 
              "enum": [0, 1],
              "description": "Email sending status: 0=DNS records pending verification, 1=fully verified and ready to send" 
            },
            "is_primary": { "type": "boolean", "description": "Whether this is the primary domain for sending emails from this workspace" },
            "verification_token": { "type": "string", "description": "Token to add as TXT record for domain ownership verification. Only returned when verification_status=0." },
            "resend_domain_id": { "type": "string", "nullable": true, "description": "External email provider domain ID (internal use)" },
            "dns_records": {
              "type": "array",
              "nullable": true,
              "description": "Required DNS records for email sending. Only returned after domain finalization (verification_status=2).",
              "items": { "$ref": "#/components/schemas/DomainDnsRecord" }
            },
            "date_created": { "type": "string", "format": "date-time", "description": "Domain creation timestamp" },
            "date_changed": { "type": "string", "format": "date-time", "description": "Domain last update timestamp" }
          }
        },
        "DomainDnsRecord": {
          "type": "object",
          "description": "DNS record required for email domain verification",
          "properties": {
            "type": { "type": "string", "enum": ["TXT", "CNAME", "MX"], "description": "DNS record type" },
            "name": { "type": "string", "description": "DNS record name/host (e.g., 'resend._domainkey' or '@')" },
            "value": { "type": "string", "description": "DNS record value" },
            "ttl": { "type": "string", "description": "Time to live (e.g., 'Auto' or seconds)" },
            "priority": { "type": "integer", "nullable": true, "description": "Priority for MX records" },
            "status": { "type": "string", "enum": ["pending", "verified", "failed"], "description": "Verification status of this specific record" }
          }
        },
        "EmailTemplate": {
          "type": "object",
          "description": "Custom email template for signing request notifications",
          "properties": {
            "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the email template" },
            "email_type": { "type": "string", "enum": ["signing_invite", "next_signer", "signing_expired", "signing_cancelled", "signing_declined"], "description": "Type of email this template is for" },
            "subject": { "type": "string", "description": "Email subject line" },
            "body": { "type": "string", "description": "Email body (HTML). Supports placeholders like {{signing_link}}, {{signer_name}}, etc." },
            "created_at": { "type": "string", "format": "date-time", "description": "Template creation timestamp" },
            "updated_at": { "type": "string", "format": "date-time", "description": "Template last update timestamp" }
          }
        },
        "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 }
          }
        }
      }
    },
    "paths": {
      "/company": {
        "get": {
          "summary": "Get company information",
          "description": "Retrieve information about the authenticated company",
          "tags": ["Company"],
          "security": [{ "ApiKeyAuth": [] }],
          "responses": {
            "200": {
              "description": "Company information retrieved successfully",
              "headers": {
                "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Rate limit: 200 requests per minute" },
                "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in current window" },
                "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when rate limit resets" }
              },
              "content": {
                "application/json": {
                  "schema": { "$ref": "#/components/schemas/Company" },
                  "example": {
                    "id": "123e4567-e89b-12d3-a456-426614174000",
                    "name": "Acme Corporation",
                    "language": "en",
                    "account_owner": "John Doe",
                    "account_owner_email": "john@acme.com",
                    "website": "https://acme.com",
                    "icon_url": "https://acme.com/logo.png",
                    "credits": 1000,
                    "created_date": "2024-01-15T10:30:00Z",
                    "updated_date": "2024-03-20T14:25:00Z"
                  }
                }
              }
            },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        },
          "put": {
          "summary": "Update company information",
          "description": "Update all company details. This is a full replacement operation requiring all fields except icon_url.",
          "tags": ["Company"],
          "security": [{ "ApiKeyAuth": [] }],
          "requestBody": {
            "required": true,
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["name", "account_owner", "account_owner_email", "website"],
                  "properties": {
                    "name": { "type": "string", "maxLength": 255, "description": "Company name" },
                    "language": { "type": "string", "enum": ["en", "es", "it", "pt", "fr", "de", "el"], "description": "Default language for the company" },
                    "account_owner": { "type": "string", "maxLength": 255, "description": "Name of the account owner" },
                    "account_owner_email": { "type": "string", "format": "email", "description": "Email address of the account owner" },
                    "website": { "type": "string", "format": "uri", "description": "Company website URL" },
                    "icon_url": { "type": "string", "format": "uri", "description": "URL to company icon/logo (optional)" }
                  },
                  "additionalProperties": false
                },
                "example": {
                  "name": "Acme Corporation Ltd",
                  "account_owner": "Jane Smith",
                  "account_owner_email": "jane@acme.com",
                  "website": "https://www.acme.com"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "Company updated successfully",
              "headers": {
                "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Rate limit: 120 requests per minute" },
                "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in current window" },
                "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when rate limit resets" }
              },
              "content": {
                "application/json": {
                  "schema": { "$ref": "#/components/schemas/Company" }
                }
              }
            },
            "400": { 
              "description": "Validation error",
              "content": {
                "application/json": {
                  "schema": { "$ref": "#/components/schemas/Error" },
                  "examples": {
                    "protectedFields": {
                      "summary": "Attempted to modify protected fields",
                      "value": {
                        "error": "The following fields cannot be modified: credits",
                        "code": "VALIDATION_ERROR"
                      }
                    }
                  }
                }
              }
            },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        },
        "patch": {
          "summary": "Partially update company information",
          "description": "Update specific company fields. Only provided fields will be updated. At least one field must be provided.",
          "tags": ["Company"],
          "security": [{ "ApiKeyAuth": [] }],
          "requestBody": {
            "required": true,
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "name": { "type": "string", "maxLength": 255, "description": "Company name" },
                    "language": { "type": "string", "enum": ["en", "es", "it", "pt", "fr", "de", "el"], "description": "Default language for the company" },
                    "account_owner": { "type": "string", "maxLength": 255, "description": "Name of the account owner" },
                    "account_owner_email": { "type": "string", "format": "email", "description": "Email address of the account owner" },
                    "website": { "type": "string", "format": "uri", "description": "Company website URL" },
                    "icon_url": { "type": "string", "format": "uri", "description": "URL to company icon/logo" }
                  },
                  "additionalProperties": false
                },
                "example": {
                  "name": "Acme Corporation Ltd",
                  "website": "https://www.acme.com"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "Company updated successfully",
              "headers": {
                "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Rate limit: 120 requests per minute" },
                "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in current window" },
                "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when rate limit resets" }
              },
              "content": {
                "application/json": {
                  "schema": { "$ref": "#/components/schemas/Company" }
                }
              }
            },
            "400": { 
              "description": "Validation error",
              "content": {
                "application/json": {
                  "schema": { "$ref": "#/components/schemas/Error" },
                  "examples": {
                    "protectedFields": {
                      "summary": "Attempted to modify protected fields",
                      "value": {
                        "error": "The following fields cannot be modified: credits",
                        "code": "VALIDATION_ERROR"
                      }
                    },
                    "noFields": {
                      "summary": "No fields provided",
                      "value": {
                        "error": "Validation failed",
                        "details": [{ "path": ["body"], "message": "No fields provided to update" }]
                      }
                    },
                    "invalidEmail": {
                      "summary": "Invalid email",
                      "value": {
                        "error": "Validation failed",
                        "details": [{ "path": ["account_owner_email"], "message": "Invalid email address" }]
                      }
                    }
                  }
                }
              }
            },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        }
      },
      "/company/domains": {
        "get": {
          "summary": "List company domains",
          "description": "List all email domains configured for the company (domains on the protected/default workspace). These domains are used as the default sending domain for all workspaces.",
          "tags": ["Email Domains"],
          "security": [{ "ApiKeyAuth": [] }],
          "responses": {
            "200": {
              "description": "Company domains retrieved successfully",
              "headers": {
                "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Rate limit: 200 requests per minute" },
                "X-RateLimit-Remaining": { "schema": { "type": "integer" } },
                "X-RateLimit-Reset": { "schema": { "type": "integer" } }
              },
              "content": {
                "application/json": {
                  "schema": {
                    "type": "object",
                    "properties": {
                      "results": { "type": "array", "items": { "$ref": "#/components/schemas/Domain" } },
                      "workspace_id": { "type": "string", "format": "uuid", "description": "ID of the protected workspace where company domains are configured" }
                    }
                  },
                  "example": {
                    "results": [
                      {
                        "id": "123e4567-e89b-12d3-a456-426614174000",
                        "domain": "acme.com",
                        "verification_status": 2,
                        "domain_status": 1,
                        "is_primary": true,
                        "date_created": "2024-01-15T10:30:00Z",
                        "date_changed": "2024-01-16T14:00:00Z"
                      }
                    ],
                    "workspace_id": "456e4567-e89b-12d3-a456-426614174000"
                  }
                }
              }
            },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        },
        "post": {
          "summary": "Add company domain",
          "description": "Add a new email domain for the company. This initiates the domain verification process. After creation, you must:\n1. Add a TXT record to your DNS with the verification token\n2. Call POST /company/domains/{id}/verify-ownership to verify domain ownership\n3. Call POST /company/domains/{id}/finalize to register with email provider\n4. Add the returned DNS records (SPF, DKIM, etc.)\n5. Call POST /company/domains/{id}/verify-dns to complete verification",
          "tags": ["Email Domains"],
          "security": [{ "ApiKeyAuth": [] }],
          "requestBody": {
            "required": true,
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["domain"],
                  "properties": {
                    "domain": { "type": "string", "description": "Domain name to add (e.g., 'example.com'). Must be a valid domain format.", "example": "acme.com" }
                  }
                }
              }
            }
          },
          "responses": {
            "201": {
              "description": "Domain created successfully. Add the verification TXT record to your DNS.",
              "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": {
                      "domain": { "$ref": "#/components/schemas/Domain" },
                      "verification_instructions": {
                        "type": "object",
                        "properties": {
                          "record_type": { "type": "string", "example": "TXT" },
                          "record_name": { "type": "string", "example": "_firma-verification.acme.com" },
                          "record_value": { "type": "string", "example": "firma-verify=abc123xyz" },
                          "next_step": { "type": "string", "example": "Add this TXT record to your DNS, then call POST /company/domains/{id}/verify-ownership" }
                        }
                      }
                    }
                  },
                  "example": {
                    "domain": {
                      "id": "123e4567-e89b-12d3-a456-426614174000",
                      "domain": "acme.com",
                      "verification_status": 0,
                      "domain_status": 0,
                      "is_primary": false,
                      "verification_token": "firma-verify=abc123xyz",
                      "date_created": "2024-01-15T10:30:00Z",
                      "date_changed": "2024-01-15T10:30:00Z"
                    },
                    "verification_instructions": {
                      "record_type": "TXT",
                      "record_name": "_firma-verification.acme.com",
                      "record_value": "firma-verify=abc123xyz",
                      "next_step": "Add this TXT record to your DNS, then call POST /company/domains/{id}/verify-ownership"
                    }
                  }
                }
              }
            },
            "400": {
              "description": "Invalid domain format or domain already exists",
              "content": {
                "application/json": {
                  "schema": { "$ref": "#/components/schemas/Error" },
                  "examples": {
                    "invalidDomain": {
                      "value": { "error": "Invalid domain format", "message": "Please provide a valid domain name (e.g., example.com)" }
                    },
                    "domainExists": {
                      "value": { "error": "Domain already exists", "message": "This domain is already configured for your company" }
                    }
                  }
                }
              }
            },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        }
      },
      "/company/domains/{id}": {
        "get": {
          "summary": "Get company domain",
          "description": "Retrieve details of a specific company domain including verification status and DNS records",
          "tags": ["Email Domains"],
          "security": [{ "ApiKeyAuth": [] }],
          "parameters": [
            { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Domain ID" }
          ],
          "responses": {
            "200": {
              "description": "Domain retrieved successfully",
              "content": {
                "application/json": {
                  "schema": { "$ref": "#/components/schemas/Domain" }
                }
              }
            },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "404": { "$ref": "#/components/responses/NotFoundError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        },
        "delete": {
          "summary": "Delete company domain",
          "description": "Remove a domain from the company. Cannot delete the primary domain if it's the only domain.",
          "tags": ["Email Domains"],
          "security": [{ "ApiKeyAuth": [] }],
          "parameters": [
            { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Domain ID" }
          ],
          "responses": {
            "200": {
              "description": "Domain deleted successfully",
              "content": {
                "application/json": {
                  "schema": {
                    "type": "object",
                    "properties": {
                      "message": { "type": "string" },
                      "domain_id": { "type": "string", "format": "uuid" }
                    }
                  },
                  "example": {
                    "message": "Domain deleted successfully",
                    "domain_id": "123e4567-e89b-12d3-a456-426614174000"
                  }
                }
              }
            },
            "400": {
              "description": "Cannot delete primary domain",
              "content": {
                "application/json": {
                  "schema": { "$ref": "#/components/schemas/Error" },
                  "example": { "error": "Cannot delete primary domain", "message": "Set another domain as primary before deleting this one" }
                }
              }
            },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "404": { "$ref": "#/components/responses/NotFoundError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        }
      },
      "/company/domains/{id}/verify-ownership": {
        "post": {
          "summary": "Verify domain ownership",
          "description": "Verify domain ownership by checking the TXT record. Call this after adding the verification TXT record to your DNS. DNS propagation may take up to 48 hours, but typically completes within minutes.",
          "tags": ["Email Domains"],
          "security": [{ "ApiKeyAuth": [] }],
          "parameters": [
            { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Domain ID" }
          ],
          "responses": {
            "200": {
              "description": "Domain ownership verified successfully",
              "content": {
                "application/json": {
                  "schema": {
                    "type": "object",
                    "properties": {
                      "message": { "type": "string" },
                      "domain": { "$ref": "#/components/schemas/Domain" },
                      "next_step": { "type": "string" }
                    }
                  },
                  "example": {
                    "message": "Domain ownership verified",
                    "domain": {
                      "id": "123e4567-e89b-12d3-a456-426614174000",
                      "domain": "acme.com",
                      "verification_status": 1,
                      "domain_status": 0
                    },
                    "next_step": "Call POST /company/domains/{id}/finalize to complete domain setup and receive DNS records for email sending"
                  }
                }
              }
            },
            "400": {
              "description": "Verification failed",
              "content": {
                "application/json": {
                  "schema": { "$ref": "#/components/schemas/Error" },
                  "examples": {
                    "recordNotFound": {
                      "value": {
                        "error": "Verification failed",
                        "message": "TXT record not found. Please ensure the record is added correctly and DNS has propagated.",
                        "details": {
                          "expected_record": "_firma-verification.acme.com",
                          "expected_value": "firma-verify=abc123xyz"
                        }
                      }
                    },
                    "alreadyVerified": {
                      "value": { "error": "Already verified", "message": "Domain ownership has already been verified" }
                    }
                  }
                }
              }
            },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "404": { "$ref": "#/components/responses/NotFoundError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        }
      },
      "/company/domains/{id}/finalize": {
        "post": {
          "summary": "Finalize domain setup",
          "description": "Finalize domain setup by registering with the email provider. This returns the DNS records (SPF, DKIM, DMARC) that must be added to enable email sending. Can only be called after domain ownership is verified.",
          "tags": ["Email Domains"],
          "security": [{ "ApiKeyAuth": [] }],
          "parameters": [
            { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Domain ID" }
          ],
          "responses": {
            "200": {
              "description": "Domain finalized successfully. Add the returned DNS records.",
              "content": {
                "application/json": {
                  "schema": {
                    "type": "object",
                    "properties": {
                      "message": { "type": "string" },
                      "domain": { "$ref": "#/components/schemas/Domain" },
                      "dns_records": {
                        "type": "array",
                        "items": { "$ref": "#/components/schemas/DomainDnsRecord" },
                        "description": "DNS records to add for email sending"
                      },
                      "next_step": { "type": "string" }
                    }
                  },
                  "example": {
                    "message": "Domain finalized. Add the following DNS records to enable email sending.",
                    "domain": {
                      "id": "123e4567-e89b-12d3-a456-426614174000",
                      "domain": "acme.com",
                      "verification_status": 2,
                      "domain_status": 0
                    },
                    "dns_records": [
                      { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "ttl": "Auto", "status": "pending" },
                      { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "ttl": "Auto", "status": "pending" },
                      { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "ttl": "Auto", "status": "pending" }
                    ],
                    "next_step": "Add these DNS records, then call POST /company/domains/{id}/verify-dns to complete verification"
                  }
                }
              }
            },
            "400": {
              "description": "Cannot finalize",
              "content": {
                "application/json": {
                  "schema": { "$ref": "#/components/schemas/Error" },
                  "examples": {
                    "notVerified": {
                      "value": { "error": "Ownership not verified", "message": "Please verify domain ownership first by calling POST /company/domains/{id}/verify-ownership" }
                    },
                    "alreadyFinalized": {
                      "value": { "error": "Already finalized", "message": "Domain has already been finalized" }
                    }
                  }
                }
              }
            },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "404": { "$ref": "#/components/responses/NotFoundError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        }
      },
      "/company/domains/{id}/verify-dns": {
        "post": {
          "summary": "Verify DNS records",
          "description": "Verify that all required DNS records (SPF, DKIM, DMARC) are properly configured. Call this after adding all DNS records from the finalize step. Once verified, the domain is ready for sending emails.",
          "tags": ["Email Domains"],
          "security": [{ "ApiKeyAuth": [] }],
          "parameters": [
            { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Domain ID" }
          ],
          "responses": {
            "200": {
              "description": "DNS verification result",
              "content": {
                "application/json": {
                  "schema": {
                    "type": "object",
                    "properties": {
                      "verified": { "type": "boolean", "description": "Whether all DNS records are verified" },
                      "message": { "type": "string" },
                      "domain": { "$ref": "#/components/schemas/Domain" },
                      "dns_records": {
                        "type": "array",
                        "items": { "$ref": "#/components/schemas/DomainDnsRecord" },
                        "description": "Status of each DNS record"
                      }
                    }
                  },
                  "examples": {
                    "verified": {
                      "summary": "All records verified",
                      "value": {
                        "verified": true,
                        "message": "Domain is fully verified and ready to send emails",
                        "domain": {
                          "id": "123e4567-e89b-12d3-a456-426614174000",
                          "domain": "acme.com",
                          "verification_status": 2,
                          "domain_status": 1,
                          "is_primary": true
                        },
                        "dns_records": [
                          { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "status": "verified" },
                          { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "status": "verified" },
                          { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "status": "verified" }
                        ]
                      }
                    },
                    "pending": {
                      "summary": "Some records pending",
                      "value": {
                        "verified": false,
                        "message": "Some DNS records are not yet verified. Please check your DNS configuration.",
                        "domain": {
                          "id": "123e4567-e89b-12d3-a456-426614174000",
                          "domain": "acme.com",
                          "verification_status": 2,
                          "domain_status": 0
                        },
                        "dns_records": [
                          { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "status": "verified" },
                          { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "status": "pending" },
                          { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "status": "pending" }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "description": "Domain not finalized",
              "content": {
                "application/json": {
                  "schema": { "$ref": "#/components/schemas/Error" },
                  "example": { "error": "Domain not finalized", "message": "Please finalize domain setup first by calling POST /company/domains/{id}/finalize" }
                }
              }
            },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "404": { "$ref": "#/components/responses/NotFoundError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        }
      },
      "/company/domains/{id}/set-primary": {
        "post": {
          "summary": "Set primary domain",
          "description": "Set a domain as the primary sending domain for the company. Only fully verified domains (domain_status=1) can be set as primary.",
          "tags": ["Email Domains"],
          "security": [{ "ApiKeyAuth": [] }],
          "parameters": [
            { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Domain ID" }
          ],
          "responses": {
            "200": {
              "description": "Primary domain updated successfully",
              "content": {
                "application/json": {
                  "schema": {
                    "type": "object",
                    "properties": {
                      "message": { "type": "string" },
                      "domain": { "$ref": "#/components/schemas/Domain" }
                    }
                  },
                  "example": {
                    "message": "Primary domain updated",
                    "domain": {
                      "id": "123e4567-e89b-12d3-a456-426614174000",
                      "domain": "acme.com",
                      "verification_status": 2,
                      "domain_status": 1,
                      "is_primary": true
                    }
                  }
                }
              }
            },
            "400": {
              "description": "Domain not verified",
              "content": {
                "application/json": {
                  "schema": { "$ref": "#/components/schemas/Error" },
                  "example": { "error": "Domain not verified", "message": "Only fully verified domains can be set as primary" }
                }
              }
            },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "404": { "$ref": "#/components/responses/NotFoundError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        }
      },
      "/workspaces": {
        "get": {
          "summary": "List workspaces",
          "description": "Retrieve a paginated list of workspaces for the authenticated company",
          "tags": ["Workspaces"],
          "security": [{ "ApiKeyAuth": [] }],
          "parameters": [
            { "name": "page", "in": "query", "description": "Page number for pagination", "schema": { "type": "integer", "minimum": 1, "default": 1 } },
            { "name": "page_size", "in": "query", "description": "Number of items per page", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } },
            { "name": "name", "in": "query", "schema": { "type": "string" }, "description": "Filter by workspace name (partial match, case-insensitive)" },
            { "name": "protected", "in": "query", "schema": { "type": "string", "enum": ["0", "1", "true", "false"] }, "description": "Filter by protected status" },
            { "name": "created_after", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Filter workspaces created after this date (ISO 8601 format)" },
            { "name": "created_before", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Filter workspaces created before this date (ISO 8601 format)" },
            { "name": "sort_by", "in": "query", "schema": { "type": "string", "enum": ["name", "protected", "created_on"], "default": "created_on" }, "description": "Field to sort by" },
            { "name": "sort_order", "in": "query", "schema": { "type": "string", "enum": ["asc", "desc"], "default": "desc" }, "description": "Sort order" }
          ],
          "responses": {
            "200": {
              "description": "Workspaces retrieved successfully",
              "headers": {
                "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Rate limit: 200 requests per minute" },
                "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in current window" },
                "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when rate limit resets" }
              },
              "content": {
                "application/json": {
                  "schema": {
                    "type": "object",
                    "properties": {
                      "results": { "type": "array", "items": { "$ref": "#/components/schemas/Workspace" } },
                      "pagination": {
                        "type": "object",
                        "properties": {
                          "current_page": { "type": "integer" },
                          "page_size": { "type": "integer" },
                          "total_count": { "type": "integer" },
                          "total_pages": { "type": "integer" }
                        }
                      }
                    }
                  },
                  "example": {
                    "results": [
                      { "id": "789e4567-e89b-12d3-a456-426614174000", "name": "Sales Workspace", "protected": false, "api_key": "fk_a1b2c3d4e5f6g7h8i9j0", "created_date": "2024-01-20T09:00:00Z", "updated_date": "2024-01-20T09:00:00Z" },
                      { "id": "456e4567-e89b-12d3-a456-426614174000", "name": "Default Workspace", "protected": true, "api_key": "fk_z9y8x7w6v5u4t3s2r1q0", "created_date": "2024-01-15T10:30:00Z", "updated_date": "2024-01-15T10:30:00Z" }
                    ],
                    "pagination": { "current_page": 1, "page_size": 20, "total_count": 2, "total_pages": 1 }
                  }
                }
              }
            },
            "400": {
              "description": "Validation error - invalid date format or sort parameters",
              "content": {
                "application/json": {
                  "examples": {
                    "invalidDate": {
                      "summary": "Invalid date format",
                      "value": {
                        "error": "Validation failed",
                        "code": "VALIDATION_ERROR",
                        "details": [{
                          "path": ["created_after"],
                          "message": "created_after must be a valid ISO 8601 date"
                        }]
                      }
                    },
                    "invalidSort": {
                      "summary": "Invalid sort parameter",
                      "value": {
                        "error": "Validation failed",
                        "code": "VALIDATION_ERROR",
                        "details": [{
                          "path": ["sort_order"],
                          "message": "sort_order must be either 'asc' or 'desc'"
                        }]
                      }
                    }
                  }
                }
              }
            },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        },
        "post": {
          "summary": "Create a new workspace",
          "description": "Create a new workspace for the authenticated company. All workspaces are created as non-protected by default. The protected status can only be set during company account creation.",
          "tags": ["Workspaces"],
          "security": [{ "ApiKeyAuth": [] }],
          "requestBody": {
            "required": true,
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["name"],
                  "properties": {
                    "name": { "type": "string", "maxLength": 255, "description": "Workspace name" }
                  }
                },
                "example": { "name": "Marketing Workspace" }
              }
            }
          },
          "responses": {
            "201": {
              "description": "Workspace created successfully",
              "headers": {
                "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Rate limit: 120 requests per minute" },
                "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in current window" },
                "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when rate limit resets" }
              },
              "content": {
                "application/json": {
                  "schema": { "$ref": "#/components/schemas/Workspace" },
                  "example": { "id": "abc12345-e89b-12d3-a456-426614174000", "name": "Marketing Workspace", "protected": false, "api_key": "fk_m1n2o3p4q5r6s7t8u9v0", "created_date": "2024-01-25T14:00:00Z", "updated_date": "2024-01-25T14:00:00Z" }
                }
              }
            },
            "400": { "$ref": "#/components/responses/ValidationError" },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        }
      },
      "/workspaces/{id}": {
        "get": {
          "summary": "Get a workspace",
          "description": "Retrieve a specific workspace by ID including its API key",
          "tags": ["Workspaces"],
          "security": [{ "ApiKeyAuth": [] }],
          "parameters": [
            { "name": "id", "in": "path", "required": true, "description": "Workspace ID", "schema": { "type": "string", "format": "uuid" } }
          ],
          "responses": {
            "200": {
              "description": "Workspace retrieved successfully",
              "headers": {
                "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Rate limit: 200 requests per minute" },
                "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in current window" },
                "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when rate limit resets" }
              },
              "content": {
                "application/json": {
                  "schema": { "$ref": "#/components/schemas/Workspace" },
                  "example": { "id": "789e4567-e89b-12d3-a456-426614174000", "name": "Sales Workspace", "protected": false, "api_key": "fk_a1b2c3d4e5f6g7h8i9j0", "created_date": "2024-01-20T09:00:00Z", "updated_date": "2024-01-20T09:00:00Z" }
                }
              }
            },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "404": { "$ref": "#/components/responses/NotFoundError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        },
        "put": {
          "summary": "Update a workspace",
          "description": "Update an existing workspace's information. This is a full replacement operation requiring the name field.",
          "tags": ["Workspaces"],
          "security": [{ "ApiKeyAuth": [] }],
          "parameters": [
            { "name": "id", "in": "path", "required": true, "description": "Workspace ID", "schema": { "type": "string", "format": "uuid" } }
          ],
          "requestBody": {
            "required": true,
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["name"],
                  "properties": {
                    "name": { "type": "string", "maxLength": 255, "description": "Workspace name" }
                  }
                },
                "example": { "name": "Enterprise Sales Workspace" }
              }
            }
          },
          "responses": {
            "200": {
              "description": "Workspace updated successfully",
              "headers": {
                "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Rate limit: 120 requests per minute" },
                "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in current window" },
                "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when rate limit resets" }
              },
              "content": {
                "application/json": {
                  "schema": { "$ref": "#/components/schemas/Workspace" }
                }
              }
            },
            "400": { "$ref": "#/components/responses/ValidationError" },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "404": { "$ref": "#/components/responses/NotFoundError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        },
        "patch": {
          "summary": "Partially update a workspace",
          "description": "Update specific workspace fields. Only the name can be updated via API. The protected field is read-only and can only be set during company account creation.",
          "tags": ["Workspaces"],
          "security": [{ "ApiKeyAuth": [] }],
          "parameters": [
            { "name": "id", "in": "path", "required": true, "description": "Workspace ID", "schema": { "type": "string", "format": "uuid" } }
          ],
          "requestBody": {
            "required": true,
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "name": { "type": "string", "maxLength": 255, "description": "Workspace name" }
                  }
                },
                "example": { "name": "Updated Workspace Name" }
              }
            }
          },
          "responses": {
            "200": {
              "description": "Workspace updated successfully",
              "headers": {
                "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Rate limit: 120 requests per minute" },
                "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in current window" },
                "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when rate limit resets" }
              },
              "content": {
                "application/json": {
                  "schema": { "$ref": "#/components/schemas/Workspace" }
                }
              }
            },
            "400": { 
              "description": "Validation error",
              "content": {
                "application/json": {
                  "examples": {
                    "protectedField": {
                      "summary": "Attempted to update protected field",
                      "value": {
                        "error": "Validation failed",
                        "details": [{ "path": ["protected"], "message": "The 'protected' field cannot be updated via API" }]
                      }
                    },
                    "noFields": {
                      "summary": "No fields provided",
                      "value": {
                        "error": "Validation failed",
                        "details": [{ "path": ["body"], "message": "No fields provided to update" }]
                      }
                    }
                  }
                }
              }
            },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "404": { "$ref": "#/components/responses/NotFoundError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        }
      },
      "/workspaces/{id}/api-key/regenerate": {
        "post": {
          "summary": "Regenerate workspace API key",
          "description": "Regenerates the API key for a workspace. Sets 24-hour expiration on existing active keys and creates a new key. Cannot be used on protected workspaces. Rate limited to 1 request per minute.",
          "tags": ["Workspaces"],
          "security": [{ "ApiKeyAuth": [] }],
          "parameters": [
            { "name": "id", "in": "path", "required": true, "description": "Workspace ID", "schema": { "type": "string", "format": "uuid" } }
          ],
          "responses": {
            "201": {
              "description": "API key regenerated successfully",
              "headers": {
                "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Rate limit: 1 request per minute" },
                "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in current window" },
                "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when rate limit resets" }
              },
              "content": {
                "application/json": {
                  "schema": {
                    "type": "object",
                    "properties": {
                      "new_key": {
                        "type": "object",
                        "description": "The newly generated API key",
                        "properties": {
                          "api_key": { "type": "string", "description": "The new API key value" },
                          "created_at": { "type": "string", "format": "date-time", "description": "When the key was created" }
                        }
                      },
                      "expiring_keys": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "properties": {
                            "id": { "type": "string", "format": "uuid" },
                            "api_key": { "type": "string", "description": "The expiring API key value" },
                            "expires_at": { "type": "string", "format": "date-time" }
                          }
                        },
                        "description": "List of keys that were set to expire in 24 hours"
                      },
                      "workspace_id": { "type": "string", "format": "uuid" }
                    }
                  },
                  "example": {
                    "new_key": {
                      "api_key": "firma_abc123xyz...",
                      "created_at": "2024-12-17T10:30:00Z"
                    },
                    "expiring_keys": [
                      {
                        "id": "old-key-uuid",
                        "api_key": "firma_old456...",
                        "expires_at": "2024-12-18T10:30:00Z"
                      }
                    ],
                    "workspace_id": "123e4567-e89b-12d3-a456-426614174000"
                  }
                }
              }
            },
            "400": {
              "description": "Cannot regenerate key for protected workspace",
              "content": {
                "application/json": {
                  "schema": { "$ref": "#/components/schemas/Error" },
                  "example": {
                    "error": "Cannot regenerate API key for protected workspace"
                  }
                }
              }
            },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "403": { "$ref": "#/components/responses/ForbiddenError" },
            "404": { "$ref": "#/components/responses/NotFoundError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        }
      },
      "/workspaces/{id}/api-key/expire": {
        "post": {
          "summary": "Expire pending API keys",
          "description": "Immediately expires all pending API keys (those with expires_at set) for a workspace. Useful after verifying that the new key works correctly. Cannot be used on protected workspaces. Rate limited to 1 request per minute.",
          "tags": ["Workspaces"],
          "security": [{ "ApiKeyAuth": [] }],
          "parameters": [
            { "name": "id", "in": "path", "required": true, "description": "Workspace ID", "schema": { "type": "string", "format": "uuid" } }
          ],
          "responses": {
            "200": {
              "description": "Pending keys expired successfully",
              "headers": {
                "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Rate limit: 1 request per minute" },
                "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in current window" },
                "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when rate limit resets" }
              },
              "content": {
                "application/json": {
                  "schema": {
                    "type": "object",
                    "properties": {
                      "success": { "type": "boolean", "description": "Whether the operation succeeded" },
                      "expired_keys": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "properties": {
                            "id": { "type": "string", "format": "uuid" },
                            "api_key": { "type": "string", "description": "The expired API key value" },
                            "original_expires_at": { "type": "string", "format": "date-time", "description": "When the key was originally set to expire" },
                            "expired_at": { "type": "string", "format": "date-time", "description": "When the key was actually expired" }
                          }
                        },
                        "description": "List of expired keys with details"
                      },
                      "workspace_id": { "type": "string", "format": "uuid" },
                      "message": { "type": "string", "description": "Optional message when no pending keys exist" }
                    }
                  },
                  "example": {
                    "success": true,
                    "expired_keys": [
                      {
                        "id": "old-key-uuid",
                        "api_key": "firma_old456...",
                        "original_expires_at": "2024-12-18T10:30:00Z",
                        "expired_at": "2024-12-17T10:30:00Z"
                      }
                    ],
                    "workspace_id": "123e4567-e89b-12d3-a456-426614174000"
                  }
                }
              }
            },
            "400": {
              "description": "Cannot expire keys for protected workspace",
              "content": {
                "application/json": {
                  "schema": { "$ref": "#/components/schemas/Error" },
                  "example": {
                    "error": "Cannot expire API keys for protected workspace"
                  }
                }
              }
            },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "403": { "$ref": "#/components/responses/ForbiddenError" },
            "404": { "$ref": "#/components/responses/NotFoundError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        }
      },
      "/templates": {
        "get": {
          "summary": "List Templates",
          "description": "Retrieve a paginated list of templates",
          "tags": ["Templates"],
          "security": [{ "ApiKeyAuth": [] }],
          "parameters": [
            { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "Page number" },
            { "name": "page_size", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Items per page" },
            { "name": "name", "in": "query", "schema": { "type": "string" }, "description": "Filter by template name (partial match, case-insensitive)" },
            { "name": "created_after", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Filter templates created after this date (ISO 8601 format)" },
            { "name": "created_before", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Filter templates created before this date (ISO 8601 format)" },
            { "name": "sort_by", "in": "query", "schema": { "type": "string", "enum": ["name", "created_on", "last_changed_on"], "default": "created_on" }, "description": "Field to sort by" },
            { "name": "sort_order", "in": "query", "schema": { "type": "string", "enum": ["asc", "desc"], "default": "desc" }, "description": "Sort order" }
          ],
          "responses": {
            "200": {
              "description": "Templates retrieved successfully",
              "headers": {
                "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Rate limit: 200 requests per minute" },
                "X-RateLimit-Remaining": { "schema": { "type": "integer" } },
                "X-RateLimit-Reset": { "schema": { "type": "integer" } }
              },
              "content": {
                "application/json": {
                  "schema": {
                    "type": "object",
                    "properties": {
                      "results": { "type": "array", "items": { "$ref": "#/components/schemas/Template" } },
                      "pagination": {
                        "type": "object",
                        "properties": {
                          "current_page": { "type": "integer" },
                          "page_size": { "type": "integer" },
                          "total_count": { "type": "integer" },
                          "total_pages": { "type": "integer" }
                        }
                      }
                    }
                  }
                }
              }
            },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        },
        "post": {
          "summary": "Create Template",
          "description": "Create a new template with a base64-encoded PDF document. The API automatically extracts the page count from the document.",
          "tags": ["Templates"],
          "security": [{ "ApiKeyAuth": [] }],
          "requestBody": {
            "required": true,
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["name", "document"],
                  "properties": {
                    "name": { 
                      "type": "string", 
                      "maxLength": 255,
                      "description": "Template name",
                      "example": "Employment Contract Template"
                    },
                    "description": { 
                      "type": "string",
                      "description": "Template description",
                      "example": "Standard employment contract for new hires"
                    },
                    "document": {
                      "type": "string",
                      "format": "byte",
                      "description": "Base64-encoded PDF or DOCX document. DOCX files are automatically converted to PDF. Maximum size: 20MB. The API will automatically extract the page count from the document.",
                      "example": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXBlIC9QYWdlCi9QYXJlbnQgMSAwIFIKL1Jlc291c..."
                    },
                    "expiration_hours": {
                      "type": "integer",
                      "description": "Hours until signing request expires",
                      "default": 168,
                      "example": 168
                    },
                    "settings": {
                      "type": "object",
                      "properties": {
                        "allow_editing_before_sending": {
                          "type": "boolean",
                          "default": false,
                          "description": "Allow editing fields before sending"
                        },
                        "attach_pdf_on_finish": {
                          "type": "boolean",
                          "default": true,
                          "description": "Attach completed PDF to completion email"
                        },
                        "allow_download": {
                          "type": "boolean",
                          "default": true,
                          "description": "Allow recipients to download the document"
                        },
                        "hand_drawn_only": {
                          "type": "boolean",
                          "default": false,
                          "description": "Require signers to hand-draw their signatures instead of using typed signatures"
                        },
                        "require_otp_verification": {
                          "type": "boolean", "nullable": true,
                          "default": null,
                          "description": "Require signers to verify their email with a one-time code. null = inherit from workspace/company."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "responses": {
            "201": {
              "description": "Template created 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": { "$ref": "#/components/schemas/Template" }
                }
              }
            },
            "400": { "$ref": "#/components/responses/ValidationError" },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        }
      },
      "/templates/{id}": {
        "get": {
          "summary": "Get Template",
          "description": "Retrieve a specific template by ID",
          "tags": ["Templates"],
          "security": [{ "ApiKeyAuth": [] }],
          "parameters": [
            { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }
          ],
          "responses": {
            "200": {
              "description": "Template retrieved successfully",
              "headers": {
                "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Rate limit: 200 requests per minute" },
                "X-RateLimit-Remaining": { "schema": { "type": "integer" } },
                "X-RateLimit-Reset": { "schema": { "type": "integer" } }
              },
              "content": {
                "application/json": {
                  "schema": { "$ref": "#/components/schemas/Template" }
                }
              }
            },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "404": { "$ref": "#/components/responses/NotFoundError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        },
        "patch": {
          "summary": "Partially Update Template",
          "description": "Update template properties, a single user, OR a single field. Cannot mix multiple entity types in one request. Use PUT for comprehensive updates including users, fields, and reminders.",
          "tags": ["Templates"],
          "security": [{ "ApiKeyAuth": [] }],
          "parameters": [
            { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }
          ],
          "requestBody": {
            "required": true,
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "type": "object",
                      "description": "Update template properties",
                      "properties": {
                        "name": { "type": "string", "maxLength": 255, "description": "Template name" },
                        "description": { "type": "string", "description": "Template description" },
                        "document": { 
                          "type": "string",
                          "format": "byte",
                          "description": "Base64-encoded PDF or DOCX to replace document. DOCX files are automatically converted to PDF. Maximum size: 20MB"
                        },
                        "expiration_hours": { "type": "integer", "minimum": 1, "description": "Hours until expiration" },
                        "settings": {
                          "type": "object",
                          "properties": {
                            "allow_editing_before_sending": { "type": "boolean" },
                            "attach_pdf_on_finish": { "type": "boolean" },
                            "allow_download": { "type": "boolean" },
                            "hand_drawn_only": { "type": "boolean" },
                            "require_otp_verification": { "type": "boolean", "nullable": true }
                          }
                        }
                      }
                    },
                    {
                      "type": "object",
                      "description": "Update or create a single user",
                      "required": ["user"],
                      "properties": {
                        "user": {
                          "type": "object",
                          "required": ["first_name", "email", "designation", "order"],
                          "properties": {
                            "id": { "type": "string", "format": "uuid", "description": "Include to update existing user, omit to create new" },
                            "first_name": { "type": "string", "maxLength": 255 },
                            "last_name": { "type": "string", "maxLength": 255, "description": "Optional, but required if using full_name or last_name prefilled variables" },
                            "email": { "type": "string", "format": "email" },
                            "designation": { "type": "string", "enum": ["Signer"] },
                            "order": { "type": "integer", "minimum": 1 },
                            "phone_number": { "type": "string" },
                            "street_address": { "type": "string" },
                            "city": { "type": "string" },
                            "state_province": { "type": "string" },
                            "postal_code": { "type": "string" },
                            "country": { "type": "string" },
                            "title": { "type": "string" },
                            "company": { "type": "string" }
                          }
                        }
                      }
                    },
                    {
                      "type": "object",
                      "description": "Update or create a single field",
                      "required": ["field"],
                      "properties": {
                        "field": {
                          "type": "object",
                          "properties": {
                            "id": { "type": "string", "format": "uuid", "description": "Include to update existing field, omit to create new" },
                            "type": { "type": "string", "enum": ["text", "signature", "date", "checkbox", "initial", "initials", "dropdown", "radio_buttons", "textarea", "text_area", "url"], "description": "Field type. Accepts 'initial' or 'initials', 'textarea' or 'text_area'. Required for new fields. url fields are automatically read-only." },
                            "x": { "type": "number", "description": "X position on document. Required for new fields." },
                            "y": { "type": "number", "description": "Y position on document. Required for new fields." },
                            "width": { "type": "number", "description": "Field width. Required for new fields." },
                            "height": { "type": "number", "description": "Field height. Required for new fields." },
                            "page": { "type": "integer", "minimum": 1, "description": "Page number (1-indexed). Required for new fields." },
                            "required": { "type": "boolean", "description": "Whether field is required" },
                            "assigned_to_user_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Template user ID to assign field to" },
                            "variable_name": { "type": "string", "description": "Variable name for prefilled data mapping" },
                            "options": { "type": "array", "items": { "type": "string" }, "description": "Options for dropdown fields" },
                            "format_rules": { "type": "object", "description": "Format rules (e.g., date format, urlDisplayText for url fields)" },
                            "multi_group_id": { "type": "string", "format": "uuid", "description": "Group ID for radio button groups" },
                            "default_to_signing_date": { "type": "boolean", "description": "For date fields, use signing date as default" },
                            "read_only": { "type": "boolean", "description": "Whether field is read-only (automatically true for url fields)" },
                            "read_only_value": { "type": "string", "description": "Static value for read-only fields. For url fields, this is the URL to link to." }
                          }
                        }
                      }
                    }
                  ]
                },
                "examples": {
                  "update-properties": {
                    "summary": "Update properties",
                    "value": {
                      "name": "Updated Template Name",
                      "expiration_hours": 72
                    }
                  },
                  "create-url-field": {
                    "summary": "Create URL field",
                    "value": {
                      "field": {
                        "type": "url",
                        "x": 100,
                        "y": 200,
                        "width": 150,
                        "height": 30,
                        "page": 1,
                        "read_only_value": "https://example.com/terms",
                        "format_rules": { "urlDisplayText": "View Terms & Conditions" }
                      }
                    }
                  },
                  "update-field": {
                    "summary": "Update existing field",
                    "value": {
                      "field": {
                        "id": "field123-e89b-12d3-a456-426614174000",
                        "x": 120,
                        "y": 220
                      }
                    }
                  }
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "Template partially updated 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": {
                      "message": { "type": "string" },
                      "updated_fields": { "type": "array", "items": { "type": "string" }, "description": "Returned when updating properties" },
                      "user": { "type": "object", "description": "Returned when updating/creating a user" }
                    }
                  }
                }
              }
            },
            "400": { "$ref": "#/components/responses/ValidationError" },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "404": { "$ref": "#/components/responses/NotFoundError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        },
        "put": {
          "summary": "Comprehensive Template Update",
          "description": "Comprehensive update of template including properties, users, fields, and reminders. Supports user deletion with field reassignment or deletion. All sections are optional but at least one must be provided.",
          "tags": ["Templates"],
          "security": [{ "ApiKeyAuth": [] }],
          "parameters": [
            { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }
          ],
          "requestBody": {
            "required": true,
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "template_properties": {
                      "type": "object",
                      "description": "Update template metadata and settings",
                      "properties": {
                        "name": { "type": "string", "maxLength": 255 },
                        "description": { "type": "string" },
                        "document": { 
                          "type": "string",
                          "format": "byte",
                          "description": "Base64-encoded PDF or DOCX to replace document. DOCX files are automatically converted to PDF. Maximum size: 20MB"
                        },
                        "expiration_hours": { "type": "integer", "minimum": 1 },
                        "settings": {
                          "type": "object",
                          "properties": {
                            "allow_editing_before_sending": { "type": "boolean" },
                            "attach_pdf_on_finish": { "type": "boolean" },
                            "allow_download": { "type": "boolean" },
                            "hand_drawn_only": { "type": "boolean" },
                            "require_otp_verification": { "type": "boolean", "nullable": true }
                          }
                        }
                      }
                    },
                    "users": {
                      "type": "array",
                      "description": "Upsert users (include id to update, omit to create)",
                      "items": {
                        "type": "object",
                        "required": ["first_name", "email", "designation", "order"],
                        "properties": {
                          "id": { "type": "string", "format": "uuid", "description": "Omit for new users" },
                          "first_name": { "type": "string" },
                          "last_name": { "type": "string", "description": "Optional, but required if using full_name or last_name prefilled variables" },
                          "email": { "type": "string", "format": "email" },
                          "designation": { "type": "string", "enum": ["Signer"] },
                          "order": { "type": "integer", "minimum": 1 },
                          "phone_number": { "type": "string" },
                          "street_address": { "type": "string" },
                          "city": { "type": "string" },
                          "state_province": { "type": "string" },
                          "postal_code": { "type": "string" },
                          "country": { "type": "string" },
                          "title": { "type": "string" },
                          "company": { "type": "string" }
                        }
                      }
                    },
                    "force_remove_conditions": { "type": "boolean", "default": false, "description": "When deleting users whose fields are referenced by conditions in other fields: if true, automatically remove the condition references; if false (default), the request will be rejected with an error." },
                    "deleted_users": {
                      "type": "array",
                      "description": "Users to delete with field handling strategy",
                      "items": {
                        "type": "object",
                        "required": ["user_id", "field_action"],
                        "properties": {
                          "user_id": { "type": "string", "format": "uuid" },
                          "field_action": { 
                            "type": "string", 
                            "enum": ["delete", "reassign"],
                            "description": "What to do with fields assigned to this user"
                          },
                          "reassign_to_user_id": { 
                            "type": "string", 
                            "format": "uuid",
                            "description": "Required when field_action is 'reassign'. Target user must have same designation."
                          }
                        }
                      }
                    },
                    "fields": {
                      "type": "array",
                      "description": "Upsert fields (include id to update, omit to create)",
                      "items": {
                        "type": "object",
                        "required": ["type", "x", "y", "width", "height", "page"],
                        "properties": {
                          "id": { "type": "string", "format": "uuid", "description": "Omit for new fields" },
                          "type": { "type": "string", "enum": ["signature", "text", "date", "checkbox", "dropdown"] },
                          "x": { "type": "number", "minimum": 0, "maximum": 100, "description": "X position as percentage" },
                          "y": { "type": "number", "minimum": 0, "maximum": 100, "description": "Y position as percentage" },
                          "width": { "type": "number", "minimum": 0, "maximum": 100 },
                          "height": { "type": "number", "minimum": 0, "maximum": 100 },
                          "page": { "type": "integer", "minimum": 1 },
                          "required": { "type": "boolean", "default": false },
                          "assigned_to_user_id": { "type": "string", "format": "uuid" },
                          "options": { "type": "array", "items": { "type": "string" }, "description": "For dropdown fields" },
                          "default_to_signing_date": { "type": "boolean", "description": "For date fields" },
                          "multi_group_id": { "type": "string", "format": "uuid", "description": "Group ID for mutually exclusive checkbox/radio button groups" },
                          "variable_name": { "type": "string" },
                          "required_conditions": { "$ref": "#/components/schemas/ConditionSet", "nullable": true },
                          "visibility_conditions": { "$ref": "#/components/schemas/ConditionSet", "nullable": true }
                        }
                      }
                    },
                    "reminders": {
                      "type": "array",
                      "description": "Upsert reminders (include id to update, omit to create)",
                      "items": {
                        "type": "object",
                        "required": ["hours", "subject", "message"],
                        "properties": {
                          "id": { "type": "string", "format": "uuid", "description": "Omit for new reminders" },
                          "hours": { "type": "integer", "minimum": 1, "description": "Hours after sending before reminder" },
                          "all_users": { "type": "boolean", "default": false },
                          "user_id": { "type": "string", "format": "uuid", "description": "Required if all_users is false" },
                          "subject": { "type": "string", "maxLength": 255 },
                          "message": { "type": "string", "maxLength": 5000 }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "Template updated successfully. Returns full template with all relationships.",
              "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/Template" }
                }
              }
            },
            "400": { "$ref": "#/components/responses/ValidationError" },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "404": { "$ref": "#/components/responses/NotFoundError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        },
        "delete": {
          "summary": "Delete a template",
          "description": "Soft delete a template by ID. This marks the template as deleted but retains the data.",
          "tags": ["Templates"],
          "security": [{ "ApiKeyAuth": [] }],
          "parameters": [
            { "name": "id", "in": "path", "required": true, "description": "Template ID", "schema": { "type": "string", "format": "uuid" } }
          ],
          "responses": {
            "200": {
              "description": "Template deleted successfully",
              "headers": {
                "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Rate limit: 120 requests per minute" },
                "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in current window" },
                "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when rate limit resets" }
              },
              "content": {
                "application/json": {
                  "schema": {
                    "type": "object",
                    "properties": {
                      "message": { "type": "string" }
                    }
                  },
                  "example": {
                    "message": "Template deleted successfully"
                  }
                }
              }
            },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "404": { "$ref": "#/components/responses/NotFoundError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        }
      },
      "/templates/{id}/users": {
        "get": {
          "summary": "Get template users",
          "description": "Retrieve all recipients/users associated with a specific template",
          "tags": ["Templates"],
          "security": [{ "ApiKeyAuth": [] }],
          "parameters": [
            { "name": "id", "in": "path", "required": true, "description": "Template ID", "schema": { "type": "string", "format": "uuid" } }
          ],
          "responses": {
            "200": {
              "description": "Template users retrieved successfully",
              "headers": {
                "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Rate limit: 200 requests per minute" },
                "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in current window" },
                "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when rate limit resets" }
              },
              "content": {
                "application/json": {
                  "schema": {
                    "type": "object",
                    "properties": {
                      "results": {
                        "type": "array",
                        "items": { "$ref": "#/components/schemas/TemplateUser" }
                      }
                    }
                  },
                  "example": {
                    "results": [
                      { 
                        "id": "abc12345-e89b-12d3-a456-426614174000", 
                        "name": "John Doe", 
                        "email": "john@example.com", 
                        "first_name": "John",
                        "last_name": "Doe",
                        "designation": "Signer", 
                        "order": 1,
                        "phone_number": null,
                        "street_address": null,
                        "city": null,
                        "state_province": null,
                        "postal_code": null,
                        "country": null,
                        "title": null,
                        "company": null,
                        "required_fields": ["email", "first_name"],
                        "missing_fields": [],
                        "required_read_only_fields": [],
                        "ready_to_send": true
                      },
                      { 
                        "id": "def67890-e89b-12d3-a456-426614174000", 
                        "name": null, 
                        "email": null, 
                        "first_name": null,
                        "last_name": null,
                        "designation": "Signer", 
                        "order": 2,
                        "phone_number": null,
                        "street_address": null,
                        "city": null,
                        "state_province": null,
                        "postal_code": null,
                        "country": null,
                        "title": null,
                        "company": null,
                        "required_fields": ["email", "first_name", "phone_number"],
                        "missing_fields": ["email", "first_name", "phone_number"],
                        "required_read_only_fields": [
                          { "variable_name": "contract_date", "field_type": "date" }
                        ],
                        "ready_to_send": false
                      }
                    ]
                  }
                }
              }
            },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "404": { "$ref": "#/components/responses/NotFoundError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        }
      },
      "/templates/{id}/fields": {
        "get": {
          "summary": "Get template fields",
          "description": "Retrieve all fields configured for a specific template",
          "tags": ["Templates"],
          "security": [{ "ApiKeyAuth": [] }],
          "parameters": [
            { "name": "id", "in": "path", "required": true, "description": "Template ID", "schema": { "type": "string", "format": "uuid" } }
          ],
          "responses": {
            "200": {
              "description": "Template fields retrieved successfully",
              "headers": {
                "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Rate limit: 200 requests per minute" },
                "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in current window" },
                "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when rate limit resets" }
              },
              "content": {
                "application/json": {
                  "schema": {
                    "type": "object",
                    "properties": {
                      "results": {
                        "type": "array",
                        "items": { "$ref": "#/components/schemas/TemplateField" }
                      }
                    }
                  },
                  "example": {
                    "results": [
                      { "id": "field123-e89b-12d3-a456-426614174000", "type": "signature", "required": true, "recipient_id": "user123-uuid", "variable_name": null, "position": { "x": 100, "y": 200, "width": 200, "height": 50 }, "page_number": 1, "dropdown_options": null, "multi_group_id": null, "date_signing_default": false, "format_rules": null, "validation_rules": null, "read_only": false, "read_only_value": null },
                      { "id": "field456-e89b-12d3-a456-426614174000", "type": "date", "required": true, "recipient_id": "user123-uuid", "variable_name": null, "position": { "x": 100, "y": 250, "width": 150, "height": 30 }, "page_number": 1, "dropdown_options": null, "multi_group_id": null, "date_signing_default": true, "format_rules": { "date_format": "MM/DD/YYYY" }, "validation_rules": null, "read_only": false, "read_only_value": null }
                    ]
                  }
                }
              }
            },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "404": { "$ref": "#/components/responses/NotFoundError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        }
      },
      "/templates/{id}/reminders": {
        "get": {
          "summary": "Get template reminders",
          "description": "Retrieve all reminders configured for a specific template",
          "tags": ["Templates"],
          "security": [{ "ApiKeyAuth": [] }],
          "parameters": [
            { "name": "id", "in": "path", "required": true, "description": "Template ID", "schema": { "type": "string", "format": "uuid" } }
          ],
          "responses": {
            "200": {
              "description": "Template reminders retrieved successfully",
              "headers": {
                "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Rate limit: 200 requests per minute" },
                "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in current window" },
                "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when rate limit resets" }
              },
              "content": {
                "application/json": {
                  "schema": {
                    "type": "array",
                    "items": { "$ref": "#/components/schemas/Reminder" }
                  },
                  "example": [
                    { "id": "remind123-e89b-12d3-a456-426614174000", "hours": 24, "subject": "Reminder: Please sign the document", "message": "This is a friendly reminder to complete your signature.", "all_users": true, "template_user_id": null, "created_date": "2024-01-15T10:30:00Z", "updated_date": "2024-01-15T10:30:00Z" }
                  ]
                }
              }
            },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "404": { "$ref": "#/components/responses/NotFoundError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        }
      },
      "/templates/{id}/replace-document": {
        "post": {
          "summary": "Replace template document",
          "description": "Replaces the PDF document of an existing template while preserving all field placements. The replacement document must have the same page count and matching page dimensions (within 1pt tolerance) as the original.",
          "tags": ["Templates"],
          "security": [{ "ApiKeyAuth": [] }],
          "parameters": [
            { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Template ID" }
          ],
          "requestBody": {
            "required": true,
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["document"],
                  "properties": {
                    "document": {
                      "type": "string",
                      "description": "Base64-encoded PDF or DOCX document. DOCX files are automatically converted to PDF."
                    }
                  }
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "Document replaced 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": { "$ref": "#/components/schemas/Template" }
                }
              }
            },
            "400": {
              "description": "Validation error (page count mismatch, dimension mismatch, invalid document)",
              "content": {
                "application/json": {
                  "schema": { "$ref": "#/components/schemas/Error" }
                }
              }
            },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "404": { "$ref": "#/components/responses/NotFoundError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        }
      },
      "/templates/{id}/duplicate": {
        "post": {
          "summary": "Duplicate template into signing request",
          "description": "Creates a new signing request by duplicating an existing template, including all fields, users, reminders, and settings.",
          "tags": ["Templates"],
          "security": [{ "ApiKeyAuth": [] }],
          "parameters": [
            { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Template ID to duplicate" }
          ],
          "requestBody": {
            "required": false,
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "name": {
                      "type": "string",
                      "maxLength": 255,
                      "description": "Custom name for the new signing request (defaults to template name)"
                    }
                  }
                },
                "example": {
                  "name": "Q4 2025 Contract"
                }
              }
            }
          },
          "responses": {
            "201": {
              "description": "Template duplicated successfully into a new signing request",
              "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": "ID of the newly created signing request" },
                      "name": { "type": "string", "description": "Name of the new signing request" },
                      "description": { "type": "string", "nullable": true, "description": "Description of the new signing request" },
                      "status": { "type": "string", "description": "Status of the new signing request", "example": "draft" },
                      "workspace_id": { "type": "string", "format": "uuid", "description": "Workspace the signing request belongs to" },
                      "created_date": { "type": "string", "format": "date-time", "description": "Creation timestamp" }
                    }
                  }
                }
              }
            },
            "403": {
              "description": "Template belongs to a different workspace",
              "content": {
                "application/json": {
                  "schema": { "$ref": "#/components/schemas/Error" }
                }
              }
            },
            "404": { "$ref": "#/components/responses/NotFoundError" },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        }
      },
      "/signing-requests": {
        "get": {
          "summary": "List Signing Requests",
          "description": "Retrieve a paginated list of signing requests",
          "tags": ["Signing Requests"],
          "security": [{ "ApiKeyAuth": [] }],
          "parameters": [
            { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "Page number" },
            { "name": "page_size", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Items per page" },
            { "name": "name", "in": "query", "schema": { "type": "string" }, "description": "Filter by signing request name (partial match, case-insensitive)" },
            { 
              "name": "status", 
              "in": "query", 
              "schema": { 
                "type": "string", 
                "enum": ["not_sent", "in_progress", "finished", "cancelled", "declined", "deleted", "expired"] 
              }, 
              "description": "Filter by signing request status. Supports multiple comma-separated values.\n\n**Available statuses:**\n- `not_sent`: Request created but not yet sent to signers\n- `in_progress`: Sent to signers but not completed, cancelled, declined, or expired\n- `finished`: All signers have completed\n- `cancelled`: Request was cancelled by sender\n- `declined`: A signer declined to sign (request stopped)\n- `deleted`: Soft-deleted records (normally hidden)\n- `expired`: Sent but past expiration time (sent_on + expiration_hours < now)\n\n**Example:** `?status=in_progress,expired`\n\n**Note:** The `expired` status uses post-filtering which may have performance implications on large datasets." 
            },
            { "name": "created_after", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Filter signing requests created after this date (ISO 8601 format)" },
            { "name": "created_before", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Filter signing requests created before this date (ISO 8601 format)" },
            { "name": "signer_email", "in": "query", "schema": { "type": "string" }, "description": "Filter by signer email address (exact match)" },
            { "name": "signer_name", "in": "query", "schema": { "type": "string" }, "description": "Filter by signer name (partial match, case-insensitive)" },
            { "name": "sort_by", "in": "query", "schema": { "type": "string", "enum": ["name", "created_on", "expiration_hours", "sent_on", "finished_on"], "default": "created_on" }, "description": "Field to sort by" },
            { "name": "sort_order", "in": "query", "schema": { "type": "string", "enum": ["asc", "desc"], "default": "desc" }, "description": "Sort order" }
          ],
          "responses": {
            "200": {
              "description": "Signing requests retrieved successfully",
              "headers": {
                "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Rate limit: 200 requests per minute" },
                "X-RateLimit-Remaining": { "schema": { "type": "integer" } },
                "X-RateLimit-Reset": { "schema": { "type": "integer" } }
              },
              "content": {
                "application/json": {
                  "schema": {
                    "type": "object",
                    "properties": {
                      "results": { "type": "array", "items": { "$ref": "#/components/schemas/SigningRequestListItem" } },
                      "pagination": {
                        "type": "object",
                        "properties": {
                          "current_page": { "type": "integer" },
                          "page_size": { "type": "integer" },
                          "total_count": { "type": "integer" },
                          "total_pages": { "type": "integer" }
                        }
                      }
                    }
                  }
                }
              }
            },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        },
        "post": {
          "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.\n\n**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.\n\n**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.",
          "tags": ["Signing Requests"],
          "security": [{ "ApiKeyAuth": [] }],
          "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" }
          }
        }
      },
      "/signing-requests/create-and-send": {
        "post": {
          "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.\n\n**Key Benefits:**\n- Single API call instead of two separate requests\n- Validates all send requirements BEFORE creating the signing request\n- Atomic credit deduction - only charges if everything succeeds\n- Returns status: 'sent' immediately with first signer details\n- More efficient (saves 1 API call + round-trip time)\n\n**Validation:**\n- All standard creation validations (document/template, recipients, fields)\n- Additional send validations:\n  - All signers must have first_name and valid email\n  - Required read-only fields must have final_value populated\n  - Prefilled data fields (variable_name) must have corresponding user data\n  - Company must have sufficient credits (≥1)\n\n**Atomicity:**\n- If any validation fails, nothing is created\n- Credit is only deducted after successful creation and before email send\n- If email send fails after creation, signing request remains in 'draft' status and credit is NOT deducted\n\n**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.\n\n**Rate Limit:** 120 requests/minute (same as write operations)",
          "tags": ["Signing Requests"],
          "security": [{ "ApiKeyAuth": [] }],
          "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"],
                            "description": "Field type",
                            "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"
                          },
                          "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"
                          }
                        }
                      }
                    },
                    "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": false,
                          "description": "Enforce signing order based on recipient.order"
                        },
                        "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"
                        }
                      }
                    }
                  },
                  "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": false,
                        "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": false,
                      "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" }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "/signing-requests/{id}": {
        "get": {
          "summary": "Get Signing Request",
          "description": "Retrieve a specific signing request by ID",
          "tags": ["Signing Requests"],
          "security": [{ "ApiKeyAuth": [] }],
          "parameters": [
            { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }
          ],
          "responses": {
            "200": {
              "description": "Signing request retrieved successfully. Returns a detailed nested shape with status as an object and timestamps grouped together.",
              "headers": {
                "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Rate limit: 200 requests per minute" },
                "X-RateLimit-Remaining": { "schema": { "type": "integer" } },
                "X-RateLimit-Reset": { "schema": { "type": "integer" } }
              },
              "content": {
                "application/json": {
                  "schema": { "$ref": "#/components/schemas/SigningRequestDetail" }
                }
              }
            },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "404": { "$ref": "#/components/responses/NotFoundError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        },
        "patch": {
          "summary": "Partially Update Signing Request",
          "description": "Update signing request properties, a single recipient, OR a single field. Cannot update multiple entity types in one request. Cannot update after signing request has been sent, completed, or cancelled.",
          "tags": ["Signing Requests"],
          "security": [{ "ApiKeyAuth": [] }],
          "parameters": [
            { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Signing request ID" }
          ],
          "requestBody": {
            "required": true,
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "type": "object",
                      "description": "Update signing request properties only",
                      "properties": {
                        "name": { "type": "string", "maxLength": 255, "description": "New name for signing request" },
                        "description": { "type": "string", "description": "New description" },
                        "document": { "type": "string", "format": "byte", "description": "Replace document with new base64-encoded PDF. Page count will be auto-extracted." },
                        "expiration_hours": { "type": "integer", "minimum": 1, "description": "New expiration hours" },
                        "settings": { "$ref": "#/components/schemas/SigningRequestSettings", "description": "Update settings" }
                      }
                    },
                    {
                      "type": "object",
                      "required": ["recipient"],
                      "description": "Create or update a single recipient",
                      "properties": {
                        "recipient": { "$ref": "#/components/schemas/Recipient", "description": "Recipient to create (omit id) or update (include id). When updating first_name or last_name, the name field is automatically reconstructed using existing values from database for any field not provided. Result: 'First Last' if both exist, 'First' if only first_name." }
                      }
                    },
                    {
                      "type": "object",
                      "required": ["field"],
                      "description": "Create or update a single field",
                      "properties": {
                        "field": {
                          "type": "object",
                          "properties": {
                            "id": { "type": "string", "format": "uuid", "description": "Include to update existing field, omit to create new" },
                            "type": { "type": "string", "enum": ["text", "signature", "date", "checkbox", "initial", "initials", "dropdown", "radio_buttons", "textarea", "text_area", "url"], "description": "Field type. Accepts 'initial' or 'initials', 'textarea' or 'text_area'. Required for new fields. url fields are automatically read-only." },
                            "position": {
                              "type": "object",
                              "properties": {
                                "x": { "type": "number", "description": "X position on document" },
                                "y": { "type": "number", "description": "Y position on document" },
                                "width": { "type": "number", "description": "Field width" },
                                "height": { "type": "number", "description": "Field height" }
                              },
                              "description": "Position object. All properties required for new fields."
                            },
                            "page_number": { "type": "integer", "minimum": 1, "description": "Page number (1-indexed). Required for new fields." },
                            "required": { "type": "boolean", "description": "Whether field is required" },
                            "recipient_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Recipient ID to assign field to" },
                            "variable_name": { "type": "string", "description": "Variable name for prefilled data mapping" },
                            "dropdown_options": { "type": "array", "items": { "type": "string" }, "description": "Options for dropdown fields" },
                            "format_rules": { "type": "object", "description": "Format rules (e.g., date format, urlDisplayText for url fields)" },
                            "validation_rules": { "type": "object", "description": "Validation rules for the field" },
                            "multi_group_id": { "type": "string", "format": "uuid", "description": "Group ID for radio button groups" },
                            "date_default": { "type": "string", "description": "Default date value" },
                            "date_signing_default": { "type": "boolean", "description": "For date fields, use signing date as default" },
                            "read_only": { "type": "boolean", "description": "Whether field is read-only (automatically true for url fields)" },
                            "read_only_value": { "type": "string", "description": "Static value for read-only fields. For url fields, this is the URL to link to." },
                            "final_value": { "type": "string", "description": "Final value of the field (for pre-filled read-only fields)" }
                          }
                        }
                      }
                    }
                  ]
                },
                "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
                      }
                    }
                  },
                  "create-url-field": {
                    "summary": "Create URL field",
                    "value": {
                      "field": {
                        "type": "url",
                        "position": { "x": 100, "y": 200, "width": 150, "height": 30 },
                        "page_number": 1,
                        "read_only_value": "https://example.com/terms",
                        "format_rules": { "urlDisplayText": "View Terms & Conditions" }
                      }
                    }
                  },
                  "update-field": {
                    "summary": "Update existing field position",
                    "value": {
                      "field": {
                        "id": "field123-e89b-12d3-a456-426614174000",
                        "position": { "x": 120, "y": 220 }
                      }
                    }
                  }
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "Signing request updated successfully. Response shape depends on what was updated: properties update returns {id, name, template_description, document_url, expiration_hours}; recipient update returns the full recipient object; field update returns the full field object. Response may include a 'warning' field 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": {
                    "oneOf": [
                      {
                        "type": "object",
                        "description": "Response when updating properties",
                        "properties": {
                          "id": { "type": "string", "format": "uuid" },
                          "name": { "type": "string" },
                          "template_description": { "type": "string", "nullable": true },
                          "document_url": { "type": "string", "format": "uri" },
                          "expiration_hours": { "type": "integer" }
                        }
                      },
                      {
                        "type": "object",
                        "description": "Response when updating/creating a recipient"
                      },
                      {
                        "type": "object",
                        "description": "Response when updating/creating a field"
                      }
                    ]
                  }
                }
              }
            },
            "400": {
              "description": "Bad Request - Cannot update both properties and recipient in same request, or signing request already sent/completed/cancelled",
              "content": {
                "application/json": {
                  "schema": { "$ref": "#/components/schemas/Error" },
                  "examples": {
                    "cannot-update-sent": {
                      "value": {
                        "error": "Cannot update signing request",
                        "message": "Signing request has already been sent and cannot be modified"
                      }
                    },
                    "mixed-update": {
                      "value": {
                        "error": "Invalid request",
                        "message": "Cannot update both properties and recipient in the same request"
                      }
                    }
                  }
                }
              }
            },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "404": { "$ref": "#/components/responses/NotFoundError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        },
        "put": {
          "summary": "Comprehensive Update Signing Request",
          "description": "Perform comprehensive updates to a signing request including properties, recipients, fields, and reminders. Cannot update after signing request has been sent, completed, or cancelled. All sections are optional but at least one must be provided.\n\n**Temporary ID Pattern for New Recipients**: When adding new recipients in a comprehensive update, use the '_temp_id' field (format: 'temp_X') instead of 'id' to establish relationships with fields and reminders. This allows you to create new recipients and reference them in fields/reminders in a single request. Use the 'id' field to update existing recipients. Validation rules: (1) Temporary IDs must start with 'temp_'; (2) Each temporary ID must be unique within the request; (3) Fields and reminders can reference temporary IDs in their recipient_id property; (4) The API will automatically resolve temporary IDs to real UUIDs after recipient creation.",
          "tags": ["Signing Requests"],
          "security": [{ "ApiKeyAuth": [] }],
          "parameters": [
            { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Signing request ID" }
          ],
          "requestBody": {
            "$ref": "#/components/requestBodies/UpdateSigningRequestBody"
          },
          "responses": {
            "200": {
              "description": "Signing request updated successfully. Returns the updated signing request and summary of changes made.",
              "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 (for backward compatibility)" },
                      "name": { "type": "string", "description": "Signing request name (for backward compatibility)" },
                      "signing_request": {
                        "type": "object",
                        "description": "Summary of the updated signing request (subset of full SigningRequest schema)",
                        "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 (mapped from template_description)" },
                          "document_url": { "type": "string", "format": "uri", "description": "Pre-signed URL to the PDF document" },
                          "document_url_expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When the document URL expires" },
                          "document_page_count": { "type": "integer", "description": "Number of pages in the document" },
                          "status": { "type": "string", "description": "Current status of the signing request" },
                          "expiration_hours": { "type": "integer", "description": "Hours until signing request expires" },
                          "settings": {
                            "type": "object",
                            "description": "Subset of signing request settings returned in PUT response",
                            "properties": {
                              "allow_download": { "type": "boolean", "description": "Whether recipients can download the document" },
                              "attach_pdf_on_finish": { "type": "boolean", "description": "Whether to attach PDF on completion" },
                              "hand_drawn_only": { "type": "boolean", "description": "Whether only hand-drawn signatures are allowed" }
                            }
                          },
                          "template_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Template ID if created from a template" },
                          "expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "ISO 8601 timestamp when the signing request expires" },
                          "created_date": { "type": "string", "format": "date-time", "description": "Creation 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", "items": { "$ref": "#/components/schemas/Recipient" }, "description": "Updated recipients list" },
                      "reminders": { "type": "array", "items": { "$ref": "#/components/schemas/Reminder" }, "description": "Updated reminders list" },
                      "summary": {
                        "type": "object",
                        "description": "Summary of all changes made in this update",
                        "properties": {
                          "properties_updated": { "type": "boolean", "description": "Whether any properties were updated" },
                          "recipients_created": { "type": "integer", "description": "Number of new recipients created" },
                          "recipients_updated": { "type": "integer", "description": "Number of existing recipients updated" },
                          "recipients_deleted": { "type": "integer", "description": "Number of recipients soft-deleted" },
                          "fields_created": { "type": "integer", "description": "Number of new fields created" },
                          "fields_updated": { "type": "integer", "description": "Number of existing fields updated" },
                          "fields_reassigned": { "type": "integer", "description": "Number of fields reassigned to another recipient" },
                          "fields_deleted": { "type": "integer", "description": "Number of fields soft-deleted" },
                          "reminders_created": { "type": "integer", "description": "Number of new reminders created" },
                          "reminders_updated": { "type": "integer", "description": "Number of existing reminders updated" },
                          "warnings": { "type": "array", "items": { "type": "string" }, "description": "Email format warnings for recipients (non-blocking)" }
                        }
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "description": "Validation errors. All section errors returned together.",
              "content": {
                "application/json": {
                  "schema": {
                    "type": "object",
                    "properties": {
                      "error": { "type": "string" },
                      "message": { "type": "string" },
                      "details": {
                        "type": "object",
                        "properties": {
                          "signing_request_properties": { "type": "array", "items": { "type": "string" } },
                          "recipients": { "type": "array", "items": { "type": "string" } },
                          "deleted_recipients": { "type": "array", "items": { "type": "string" } },
                          "fields": { "type": "array", "items": { "type": "string" } },
                          "reminders": { "type": "array", "items": { "type": "string" } }
                        }
                      }
                    }
                  },
                  "example": {
                    "error": "Validation failed",
                    "message": "Multiple validation errors occurred",
                    "details": {
                      "recipients": ["Recipient 1: email is invalid"],
                      "deleted_recipients": ["Cannot reassign: designations must match"],
                      "fields": ["Field 2: x coordinate must be between 0 and 100"]
                    }
                  }
                }
              }
            },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "404": { "$ref": "#/components/responses/NotFoundError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        }
      },
      "/signing-requests/{id}/users": {
        "get": {
          "summary": "Get signing request users",
          "description": "Retrieve all recipients/users for a specific signing request",
          "tags": ["Signing Requests"],
          "security": [{ "ApiKeyAuth": [] }],
          "parameters": [
            { "name": "id", "in": "path", "required": true, "description": "Signing request ID", "schema": { "type": "string", "format": "uuid" } }
          ],
          "responses": {
            "200": {
              "description": "Signing request users retrieved successfully",
              "headers": {
                "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Rate limit: 200 requests per minute" },
                "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in current window" },
                "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when rate limit resets" }
              },
              "content": {
                "application/json": {
                  "schema": {
                    "type": "object",
                    "properties": {
                      "results": {
                        "type": "array",
                        "items": { "$ref": "#/components/schemas/SigningRequestUser" }
                      }
                    }
                  },
                  "example": {
                    "results": [
                      { 
                        "id": "user123-e89b-12d3-a456-426614174000", 
                        "name": "Alice Johnson", 
                        "email": "alice@example.com", 
                        "first_name": "Alice",
                        "last_name": "Johnson",
                        "designation": "Signer", 
                        "order": 1, 
                        "finished_on": "2024-03-15T14:30:00Z",
                        "declined_on": null,
                        "decline_reason": null,
                        "phone_number": "+1-555-0101",
                        "street_address": null,
                        "city": null,
                        "state_province": null,
                        "postal_code": null,
                        "country": null,
                        "title": "CEO",
                        "company": "Acme Corp",
                        "custom_fields": null,
                        "required_fields": ["email", "first_name"],
                        "missing_fields": [],
                        "required_read_only_fields": [],
                        "ready_to_send": true
                      },
                      { 
                        "id": "user456-e89b-12d3-a456-426614174000", 
                        "name": "Bob Williams", 
                        "email": "bob@example.com", 
                        "first_name": "Bob",
                        "last_name": "Williams",
                        "designation": "Signer", 
                        "order": 2, 
                        "finished_on": null,
                        "declined_on": null,
                        "decline_reason": null,
                        "phone_number": null,
                        "street_address": null,
                        "city": null,
                        "state_province": null,
                        "postal_code": null,
                        "country": null,
                        "title": null,
                        "company": null,
                        "custom_fields": null,
                        "required_fields": ["email", "first_name", "phone_number"],
                        "missing_fields": ["phone_number"],
                        "required_read_only_fields": [
                          { "variable_name": "contract_amount", "field_type": "number", "has_value": false }
                        ],
                        "ready_to_send": false
                      }
                    ]
                  }
                }
              }
            },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "404": { "$ref": "#/components/responses/NotFoundError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        }
      },
      "/signing-requests/{id}/fields": {
        "get": {
          "summary": "Get signing request fields",
          "description": "Retrieve all fields for a specific signing request with their values",
          "tags": ["Signing Requests"],
          "security": [{ "ApiKeyAuth": [] }],
          "parameters": [
            { "name": "id", "in": "path", "required": true, "description": "Signing request ID", "schema": { "type": "string", "format": "uuid" } }
          ],
          "responses": {
            "200": {
              "description": "Signing request fields retrieved successfully",
              "headers": {
                "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Rate limit: 200 requests per minute" },
                "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in current window" },
                "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when rate limit resets" }
              },
              "content": {
                "application/json": {
                  "schema": {
                    "type": "object",
                    "properties": {
                      "results": {
                        "type": "array",
                        "items": { "$ref": "#/components/schemas/SigningRequestField" }
                      }
                    }
                  },
                  "example": {
                    "results": [
                      { 
                        "id": "field789-e89b-12d3-a456-426614174000", 
                        "companies_workspaces_signing_requests_id": "sr123-e89b-12d3-a456-426614174000",
                        "companies_workspaces_signing_requests_users_id": "user456-e89b-12d3-a456-426614174000",
                        "field_type": "signature", 
                        "required": 1,
                        "x_postion": 100.5,
                        "y_position": 200.75,
                        "width": 200,
                        "heigh": 50,
                        "page_number": 1,
                        "final_value": "data:image/png;base64,iVBOR...",
                        "read_only": 0,
                        "deleted": 0
                      },
                      { 
                        "id": "field012-e89b-12d3-a456-426614174000", 
                        "companies_workspaces_signing_requests_id": "sr123-e89b-12d3-a456-426614174000",
                        "companies_workspaces_signing_requests_users_id": "user456-e89b-12d3-a456-426614174000",
                        "field_type": "text", 
                        "required": 1,
                        "x_postion": 150,
                        "y_position": 300,
                        "width": 250,
                        "heigh": 30,
                        "page_number": 1,
                        "variable_name": "full_name",
                        "final_value": "Alice Johnson",
                        "read_only": 0,
                        "deleted": 0
                      }
                    ]
                  }
                }
              }
            },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "404": { "$ref": "#/components/responses/NotFoundError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        }
      },
      "/signing-requests/{id}/reminders": {
        "get": {
          "summary": "Get signing request reminders",
          "description": "Retrieve all reminders scheduled for a specific signing request",
          "tags": ["Signing Requests"],
          "security": [{ "ApiKeyAuth": [] }],
          "parameters": [
            { "name": "id", "in": "path", "required": true, "description": "Signing request ID", "schema": { "type": "string", "format": "uuid" } }
          ],
          "responses": {
            "200": {
              "description": "Signing request reminders retrieved successfully",
              "headers": {
                "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Rate limit: 200 requests per minute" },
                "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in current window" },
                "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when rate limit resets" }
              },
              "content": {
                "application/json": {
                  "schema": {
                    "type": "array",
                    "items": { "$ref": "#/components/schemas/Reminder" }
                  },
                  "example": [
                    { "id": "remind789-e89b-12d3-a456-426614174000", "hours": 48, "subject": "Urgent: Document signature required", "message": "Please complete your signature at your earliest convenience.", "all_users": false, "template_user_id": "user456-e89b-12d3-a456-426614174000", "date_created": "2024-03-10T09:00:00Z", "date_changed": "2024-03-10T09:00:00Z" }
                  ]
                }
              }
            },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "404": { "$ref": "#/components/responses/NotFoundError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        }
      },
      "/signing-requests/{id}/audit": {
        "get": {
          "summary": "Get signing request audit trail",
          "description": "Retrieve the complete audit trail for a signing request, combining admin actions (created, edited, sent, cancelled) and signer actions (viewed, signed, declined, downloaded). Events are sorted chronologically.",
          "tags": ["Signing Requests"],
          "security": [{ "ApiKeyAuth": [] }],
          "parameters": [
            { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Signing request ID" }
          ],
          "responses": {
            "200": {
              "description": "Audit trail retrieved 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": {
                      "results": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "properties": {
                            "id": { "type": "string", "format": "uuid" },
                            "timestamp": { "type": "string", "format": "date-time" },
                            "source": { "type": "string", "enum": ["admin", "signer"], "description": "Whether the event was triggered by an admin/API or a signer" },
                            "event": { "type": "string", "description": "Event type identifier" },
                            "description": { "type": "string", "description": "Human-readable event description" },
                            "actor": { "type": "object", "nullable": true, "description": "Who performed the action (signer name/email or admin/API key)" },
                            "ip_address": { "type": "string", "nullable": true, "description": "IP address of the signer (signer events only)" },
                            "details": { "type": "object", "nullable": true, "description": "Additional event-specific metadata" }
                          }
                        }
                      }
                    }
                  }
                }
              }
            },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "404": { "$ref": "#/components/responses/NotFoundError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        }
      },
      "/signing-requests/{id}/send": {
        "post": {
          "summary": "Send signing request",
          "description": "Send a signing request to all recipients via email. This triggers email delivery and sets the sent_on timestamp.",
          "tags": ["Signing Requests"],
          "security": [{ "ApiKeyAuth": [] }],
          "parameters": [
            { "name": "id", "in": "path", "required": true, "description": "Signing request ID", "schema": { "type": "string", "format": "uuid" } }
          ],
          "responses": {
            "200": {
              "description": "Signing request sent successfully",
              "headers": {
                "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Rate limit: 60 requests per minute" },
                "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in current window" },
                "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when rate limit resets" }
              },
              "content": {
                "application/json": {
                  "schema": { "$ref": "#/components/schemas/SendSigningRequestResponse" },
                  "example": {
                    "message": "Signing request sent successfully",
                    "signing_request_id": "123e4567-e89b-12d3-a456-426614174000",
                    "recipients_notified": 3,
                    "sent_date": "2024-03-20T10:15:00Z",
                    "expires_at": "2024-04-20T10:15:00Z"
                  }
                }
              }
            },
            "400": {
              "description": "Bad Request - Signing request already sent or expired",
              "content": {
                "application/json": {
                  "schema": { "$ref": "#/components/schemas/Error" },
                  "examples": {
                    "alreadySent": {
                      "value": { "error": "Bad Request", "message": "Signing request has already been sent" }
                    },
                    "expired": {
                      "value": { "error": "Bad Request", "message": "Signing request has expired" }
                    }
                  }
                }
              }
            },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "404": { "$ref": "#/components/responses/NotFoundError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        }
      },
      "/signing-requests/{id}/cancel": {
        "post": {
          "summary": "Cancel a signing request",
          "description": "Cancels a signing request that hasn't been completed yet. Can only cancel requests that have been sent and are not already finished or cancelled.",
          "tags": ["Signing Requests"],
          "security": [{ "ApiKeyAuth": [] }],
          "parameters": [
            { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Signing request ID" }
          ],
          "requestBody": {
            "required": false,
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "reason": { "type": "string", "maxLength": 500, "description": "Optional cancellation reason" },
                    "notify_signers": { "type": "boolean", "default": true, "description": "Whether to notify signers of cancellation" }
                  }
                },
                "example": {
                  "reason": "No longer needed",
                  "notify_signers": true
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "Signing request cancelled 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": {
                      "message": { "type": "string" },
                      "signing_request_id": { "type": "string", "format": "uuid" },
                      "cancelled_on": { "type": "string", "format": "date-time" },
                      "notify_signers": { "type": "boolean" }
                    }
                  }
                }
              }
            },
            "404": { "$ref": "#/components/responses/NotFoundError" },
            "409": {
              "description": "Cannot cancel (already cancelled, finished, or not sent)",
              "content": {
                "application/json": {
                  "schema": { "$ref": "#/components/schemas/Error" }
                }
              }
            },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        }
      },
      "/signing-requests/{id}/resend": {
        "post": {
          "summary": "Resend signing request to specific recipients",
          "description": "Resends signing request notifications to one or more recipients who are currently eligible to sign. For requests with signing order enabled, can only resend to recipients at the current active order. Cannot resend to recipients who have already signed.",
          "tags": ["Signing Requests"],
          "security": [{ "ApiKeyAuth": [] }],
          "parameters": [
            { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Signing request ID" }
          ],
          "requestBody": {
            "required": true,
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["recipient_ids"],
                  "properties": {
                    "recipient_ids": {
                      "type": "array",
                      "items": { "type": "string", "format": "uuid" },
                      "description": "Array of recipient user IDs to resend to",
                      "minItems": 1
                    },
                    "custom_message": {
                      "type": "string",
                      "maxLength": 1000,
                      "description": "Optional custom message to include in resend notification"
                    }
                  }
                },
                "example": {
                  "recipient_ids": ["123e4567-e89b-12d3-a456-426614174000"],
                  "custom_message": "Gentle reminder to complete your signature"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "Signing request resent 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": {
                      "message": { "type": "string" },
                      "signing_request_id": { "type": "string", "format": "uuid" },
                      "recipients_notified": { "type": "integer" },
                      "recipients": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "properties": {
                            "id": { "type": "string", "format": "uuid" },
                            "email": { "type": "string" },
                            "name": { "type": "string" }
                          }
                        }
                      }
                    }
                  }
                }
              }
            },
            "400": { "$ref": "#/components/responses/ValidationError" },
            "404": { "$ref": "#/components/responses/NotFoundError" },
            "409": {
              "description": "Cannot resend (recipients already signed, invalid signing order, or request not sent/cancelled/finished)",
              "content": {
                "application/json": {
                  "schema": {
                    "type": "object",
                    "properties": {
                      "error": { "type": "string" },
                      "code": { "type": "string" },
                      "details": {
                        "type": "object",
                        "properties": {
                          "current_order": { "type": "integer" },
                          "invalid_recipients": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "id": { "type": "string", "format": "uuid" },
                                "email": { "type": "string" },
                                "order": { "type": "integer" }
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        }
      },
      "/webhooks": {
        "get": {
          "summary": "List Webhooks",
          "description": "Retrieve a paginated list of webhooks",
          "tags": ["Webhooks"],
          "security": [{ "ApiKeyAuth": [] }],
          "parameters": [
            { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "Page number" },
            { "name": "page_size", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Items per page" },
            { "name": "enabled", "in": "query", "schema": { "type": "string", "enum": ["0", "1"] }, "description": "Filter by enabled status (0=disabled, 1=enabled)" },
            { "name": "url", "in": "query", "schema": { "type": "string" }, "description": "Filter by webhook URL (partial match, case-insensitive)" },
            { "name": "event", "in": "query", "schema": { "type": "string" }, "description": "Filter by event type (e.g., 'signing_request.completed')" },
            { "name": "created_after", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Filter webhooks created after this date (ISO 8601 format)" },
            { "name": "created_before", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Filter webhooks created before this date (ISO 8601 format)" },
            { "name": "sort_by", "in": "query", "schema": { "type": "string", "enum": ["url", "enabled", "created_on", "last_changed_on", "consecutive_failures"], "default": "created_on" }, "description": "Field to sort by" },
            { "name": "sort_order", "in": "query", "schema": { "type": "string", "enum": ["asc", "desc"], "default": "desc" }, "description": "Sort order" }
          ],
          "responses": {
            "200": {
              "description": "Webhooks retrieved successfully",
              "headers": {
                "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Rate limit: 200 requests per minute" },
                "X-RateLimit-Remaining": { "schema": { "type": "integer" } },
                "X-RateLimit-Reset": { "schema": { "type": "integer" } }
              },
              "content": {
                "application/json": {
                  "schema": {
                    "type": "object",
                    "properties": {
                      "results": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } },
                      "pagination": {
                        "type": "object",
                        "properties": {
                          "current_page": { "type": "integer" },
                          "page_size": { "type": "integer" },
                          "total_count": { "type": "integer" },
                          "total_pages": { "type": "integer" }
                        }
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "description": "Validation error - invalid date format or sort parameters",
              "content": {
                "application/json": {
                  "examples": {
                    "invalidDate": {
                      "summary": "Invalid date format",
                      "value": {
                        "error": "Validation failed",
                        "code": "VALIDATION_ERROR",
                        "details": [{
                          "path": ["created_before"],
                          "message": "created_before must be a valid ISO 8601 date"
                        }]
                      }
                    },
                    "invalidSort": {
                      "summary": "Invalid sort parameter",
                      "value": {
                        "error": "Validation failed",
                        "code": "VALIDATION_ERROR",
                        "details": [{
                          "path": ["sort_by"],
                          "message": "Invalid sort field"
                        }]
                      }
                    }
                  }
                }
              }
            },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        },
        "post": {
          "summary": "Create Webhook",
          "description": "Create a new webhook",
          "tags": ["Webhooks"],
          "security": [{ "ApiKeyAuth": [] }],
          "requestBody": {
            "required": true,
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["url", "events"],
                  "properties": {
                    "url": { "type": "string", "format": "uri" },
                    "events": { "type": "array", "items": { "type": "string" } }
                  }
                }
              }
            }
          },
          "responses": {
            "201": {
              "description": "Webhook created successfully",
              "headers": {
                "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Rate limit: 60 requests per minute" },
                "X-RateLimit-Remaining": { "schema": { "type": "integer" } },
                "X-RateLimit-Reset": { "schema": { "type": "integer" } }
              },
              "content": {
                "application/json": {
                  "schema": { "$ref": "#/components/schemas/Webhook" }
                }
              }
            },
            "400": { "$ref": "#/components/responses/ValidationError" },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        }
      },
      "/webhooks/{id}": {
        "get": {
          "summary": "Get Webhook",
          "description": "Retrieve a specific webhook by ID",
          "tags": ["Webhooks"],
          "security": [{ "ApiKeyAuth": [] }],
          "parameters": [
            { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }
          ],
          "responses": {
            "200": {
              "description": "Webhook retrieved successfully",
              "headers": {
                "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Rate limit: 200 requests per minute" },
                "X-RateLimit-Remaining": { "schema": { "type": "integer" } },
                "X-RateLimit-Reset": { "schema": { "type": "integer" } }
              },
              "content": {
                "application/json": {
                  "schema": { "$ref": "#/components/schemas/Webhook" }
                }
              }
            },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "404": { "$ref": "#/components/responses/NotFoundError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        },
        "put": {
          "summary": "Update Webhook",
          "description": "Update an existing webhook",
          "tags": ["Webhooks"],
          "security": [{ "ApiKeyAuth": [] }],
          "parameters": [
            { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }
          ],
          "requestBody": {
            "required": true,
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "url": { "type": "string", "format": "uri" },
                    "events": { "type": "array", "items": { "type": "string" } }
                  }
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "Webhook updated successfully",
              "headers": {
                "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Rate limit: 60 requests per minute" },
                "X-RateLimit-Remaining": { "schema": { "type": "integer" } },
                "X-RateLimit-Reset": { "schema": { "type": "integer" } }
              },
              "content": {
                "application/json": {
                  "schema": { "$ref": "#/components/schemas/Webhook" }
                }
              }
            },
            "400": { "$ref": "#/components/responses/ValidationError" },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "404": { "$ref": "#/components/responses/NotFoundError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        },
        "delete": {
          "summary": "Delete a webhook",
          "description": "Soft delete a webhook by ID. This marks the webhook as deleted but retains the data.",
          "tags": ["Webhooks"],
          "security": [{ "ApiKeyAuth": [] }],
          "parameters": [
            { "name": "id", "in": "path", "required": true, "description": "Webhook ID", "schema": { "type": "string", "format": "uuid" } }
          ],
          "responses": {
            "200": {
              "description": "Webhook deleted successfully",
              "headers": {
                "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Rate limit: 60 requests per minute" },
                "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in current window" },
                "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when rate limit resets" }
              },
              "content": {
                "application/json": {
                  "schema": {
                    "type": "object",
                    "properties": {
                      "message": { "type": "string" }
                    }
                  },
                  "example": {
                    "message": "Webhook deleted successfully"
                  }
                }
              }
            },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "404": { "$ref": "#/components/responses/NotFoundError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        }
      },
      "/webhooks/{id}/test": {
        "post": {
          "summary": "Test a webhook",
          "description": "Send a test payload to the webhook URL to verify it's working correctly",
          "tags": ["Webhooks"],
          "security": [{ "ApiKeyAuth": [] }],
          "parameters": [
            { "name": "id", "in": "path", "required": true, "description": "Webhook ID", "schema": { "type": "string", "format": "uuid" } }
          ],
          "responses": {
            "200": {
              "description": "Test webhook sent successfully",
              "headers": {
                "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Rate limit: 10 requests per minute" },
                "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in current window" },
                "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when rate limit resets" }
              },
              "content": {
                "application/json": {
                  "schema": {
                    "type": "object",
                    "properties": {
                      "success": { "type": "boolean", "description": "Whether the test webhook was delivered successfully" },
                      "status_code": { "type": "integer", "description": "HTTP status code returned by the webhook endpoint" },
                      "webhook_event_id": { "type": "string", "format": "uuid", "description": "ID of the webhook event record" },
                      "message": { "type": "string" },
                      "headers_sent": {
                        "type": "object",
                        "description": "Headers sent with the test webhook request",
                        "properties": {
                          "X-Firma-Event": { "type": "string" },
                          "X-Firma-Signature": { "type": "string" },
                          "X-Firma-Delivery": { "type": "string" },
                          "X-Firma-Signature-Old": { "type": "string", "description": "Only present during grace period after secret rotation" }
                        }
                      }
                    }
                  },
                  "example": {
                    "success": true,
                    "status_code": 200,
                    "webhook_event_id": "123e4567-e89b-12d3-a456-426614174000",
                    "message": "Test webhook delivered successfully",
                    "headers_sent": {
                      "X-Firma-Event": "webhook.test",
                      "X-Firma-Signature": "Generated HMAC-SHA256 signature",
                      "X-Firma-Delivery": "123e4567-e89b-12d3-a456-426614174000"
                    }
                  }
                }
              }
            },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "404": { "$ref": "#/components/responses/NotFoundError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        }
      },
      "/webhooks/rotate-secret": {
        "post": {
          "summary": "Rotate webhook signing secret",
          "description": "Generates a new webhook signing secret for the company. The old secret remains valid for 7 days to allow graceful migration. Rate limited to 1 request per minute.",
          "tags": ["Webhooks"],
          "security": [{ "ApiKeyAuth": [] }],
          "responses": {
            "200": {
              "description": "Secret rotated successfully",
              "headers": {
                "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Rate limit: 1 request per minute" },
                "X-RateLimit-Remaining": { "schema": { "type": "integer" } },
                "X-RateLimit-Reset": { "schema": { "type": "integer" } }
              },
              "content": {
                "application/json": {
                  "schema": {
                    "type": "object",
                    "properties": {
                      "message": { "type": "string" },
                      "new_secret": { "type": "string", "description": "The new webhook signing secret (64 character hex string)" },
                      "grace_period_hours": { "type": "integer", "description": "Hours the old secret remains valid alongside the new one" },
                      "warning": { "type": "string", "description": "Reminder to update webhook signature verification" }
                    }
                  },
                  "example": {
                    "message": "Webhook secret rotated successfully",
                    "new_secret": "a1b2c3d4e5f6...",
                    "grace_period_hours": 168,
                    "warning": "Update your webhook signature verification to use the new secret. The old secret will remain valid for 7 days."
                  }
                }
              }
            },
            "429": {
              "description": "Rate limit exceeded (1 rotation per minute)",
              "content": {
                "application/json": {
                  "schema": { "$ref": "#/components/schemas/Error" }
                }
              }
            },
            "401": { "$ref": "#/components/responses/UnauthorizedError" }
          }
        }
      },
      "/webhooks/secret-status": {
        "get": {
          "summary": "Get webhook secret rotation status",
          "description": "Returns information about the current webhook secret including rotation status and expiry of old secret if applicable.",
          "tags": ["Webhooks"],
          "security": [{ "ApiKeyAuth": [] }],
          "responses": {
            "200": {
              "description": "Secret status retrieved successfully",
              "headers": {
                "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Rate limit: 200 requests per minute" },
                "X-RateLimit-Remaining": { "schema": { "type": "integer" } },
                "X-RateLimit-Reset": { "schema": { "type": "integer" } }
              },
              "content": {
                "application/json": {
                  "schema": {
                    "type": "object",
                    "properties": {
                      "created_at": { "type": "string", "format": "date-time", "description": "When the webhook secret was created", "nullable": true },
                      "last_rotated_at": {
                        "type": "string",
                        "format": "date-time",
                        "description": "When the webhook secret was last rotated",
                        "nullable": true
                      },
                      "grace_period_active": { "type": "boolean", "description": "Whether the old secret is still valid alongside the new one" },
                      "grace_period_ends_at": {
                        "type": "string",
                        "format": "date-time",
                        "description": "When the old secret grace period expires",
                        "nullable": true
                      }
                    }
                  },
                  "example": {
                    "created_at": "2025-09-01T10:00:00Z",
                    "last_rotated_at": "2025-10-16T12:00:00Z",
                    "grace_period_active": true,
                    "grace_period_ends_at": "2025-10-23T12:00:00Z"
                  }
                }
              }
            },
            "404": {
              "description": "No webhook configuration found",
              "content": {
                "application/json": {
                  "schema": { "$ref": "#/components/schemas/Error" }
                }
              }
            },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        }
      },
      "/generate-template-token": {
        "post": {
          "summary": "Generate JWT token for embedding templates",
          "description": "Creates a JWT token for embedding a template with 24-hour expiration. This is the standard endpoint for JWT generation.\n\n**Note**: The standalone `generate-embedded-template-token` function is deprecated in favor of this router-based endpoint.",
          "tags": ["JWT Management"],
          "security": [{ "ApiKeyAuth": [] }],
          "requestBody": {
            "required": true,
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/GenerateJWTRequest" },
                "example": {
                  "companies_workspaces_templates_id": "123e4567-e89b-12d3-a456-426614174000"
                }
              }
            }
          },
          "responses": {
            "201": {
              "description": "JWT generated successfully",
              "headers": {
                "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Rate limit: 120 requests per minute" },
                "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in current window" },
                "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when rate limit resets" }
              },
              "content": {
                "application/json": {
                  "schema": {
                    "type": "object",
                    "properties": {
                      "token": { "type": "string", "description": "The JWT token" },
                      "expires_at": { "type": "string", "format": "date-time", "description": "Token expiration timestamp" },
                      "jwt_record_id": { "type": "string", "format": "uuid", "description": "Database record ID for the JWT" }
                    }
                  },
                  "example": {
                    "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
                    "expires_at": "2024-04-20T10:00:00Z",
                    "jwt_record_id": "jwt123-e89b-12d3-a456-426614174000"
                  }
                }
              }
            },
            "400": { "$ref": "#/components/responses/ValidationError" },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "404": { "$ref": "#/components/responses/NotFoundError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        }
      },
      "/revoke-template-token": {
        "post": {
          "summary": "Revoke Template JWT Token",
          "description": "Revoke a previously generated JWT token, preventing it from being used for template embedding. This is the standard endpoint for revoking template JWTs.",
          "tags": ["JWT Management"],
          "security": [{ "ApiKeyAuth": [] }],
          "requestBody": {
            "required": true,
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/RevokeJWTRequest" },
                "example": {
                  "jwt_id": "123e4567-e89b-12d3-a456-426614174000"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "JWT revoked successfully",
              "headers": {
                "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Rate limit: 120 requests per minute" },
                "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in current window" },
                "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when rate limit resets" }
              },
              "content": {
                "application/json": {
                  "schema": { "$ref": "#/components/schemas/RevokeJWTResponse" },
                  "example": {
                    "message": "JWT revoked successfully",
                    "jwt_id": "123e4567-e89b-12d3-a456-426614174000",
                    "revoked_at": "2024-03-20T16:45:00Z"
                  }
                }
              }
            },
            "400": {
              "description": "Bad Request - JWT already revoked or invalid",
              "content": {
                "application/json": {
                  "schema": { "$ref": "#/components/schemas/Error" },
                  "examples": {
                    "alreadyRevoked": {
                      "value": { "error": "Bad Request", "message": "JWT has already been revoked" }
                    },
                    "invalidJwt": {
                      "value": { "error": "Bad Request", "message": "Invalid JWT ID" }
                    }
                  }
                }
              }
            },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "404": { "$ref": "#/components/responses/NotFoundError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        }
      },
      "/jwt/generate-signing-request": {
        "post": {
          "summary": "Generate JWT token for signing request",
          "description": "Generate a JWT token for embedding a signing request editor. JWT expires after 7 days.",
          "tags": ["JWT Management"],
          "security": [{ "ApiKeyAuth": [] }],
          "requestBody": {
            "required": true,
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/GenerateSigningRequestJWTRequest" },
                "example": {
                  "companies_workspaces_signing_requests_id": "123e4567-e89b-12d3-a456-426614174000"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "JWT generated successfully",
              "headers": {
                "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Rate limit: 120 requests per minute" },
                "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in current window" },
                "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when rate limit resets" }
              },
              "content": {
                "application/json": {
                  "schema": { "$ref": "#/components/schemas/GenerateSigningRequestJWTResponse" },
                  "example": {
                    "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
                    "jwt_id": "jwt123-e89b-12d3-a456-426614174000",
                    "expires_at": "2024-03-27T10:00:00Z",
                    "signing_request_id": "123e4567-e89b-12d3-a456-426614174000"
                  }
                }
              }
            },
            "400": { "$ref": "#/components/responses/ValidationError" },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "404": { "$ref": "#/components/responses/NotFoundError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        }
      },
      "/jwt/revoke-signing-request": {
        "post": {
          "summary": "Revoke a signing request JWT token",
          "description": "Revoke a previously generated JWT token for a signing request, preventing it from being used for embedded editing",
          "tags": ["JWT Management"],
          "security": [{ "ApiKeyAuth": [] }],
          "requestBody": {
            "required": true,
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/RevokeSigningRequestJWTRequest" },
                "example": {
                  "jwt_id": "123e4567-e89b-12d3-a456-426614174000"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "JWT revoked successfully",
              "headers": {
                "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Rate limit: 120 requests per minute" },
                "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in current window" },
                "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when rate limit resets" }
              },
              "content": {
                "application/json": {
                  "schema": { "$ref": "#/components/schemas/RevokeSigningRequestJWTResponse" },
                  "example": {
                    "message": "JWT revoked successfully",
                    "jwt_id": "123e4567-e89b-12d3-a456-426614174000",
                    "revoked_at": "2024-03-20T16:45:00Z"
                  }
                }
              }
            },
            "400": {
              "description": "Bad Request - JWT already revoked or invalid",
              "content": {
                "application/json": {
                  "schema": { "$ref": "#/components/schemas/Error" },
                  "examples": {
                    "alreadyRevoked": {
                      "value": { "error": "Bad Request", "message": "JWT has already been revoked" }
                    },
                    "invalidJwt": {
                      "value": { "error": "Bad Request", "message": "Invalid JWT ID" }
                    }
                  }
                }
              }
            },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "404": { "$ref": "#/components/responses/NotFoundError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        }
      },
      "/save-embedded-signing-request": {
        "post": {
          "summary": "Save embedded signing request (JWT authenticated)",
          "description": "Save changes to a signing request when using embedded editor. Requires JWT authentication obtained from `/jwt/generate-signing-request`.",
          "tags": ["Signing Requests"],
          "security": [{ "ApiKeyAuth": [] }],
          "requestBody": {
            "required": true,
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["companies_workspaces_signing_requests_id"],
                  "properties": {
                    "companies_workspaces_signing_requests_id": { "type": "string", "format": "uuid" },
                    "fields": { "type": "array", "items": { "$ref": "#/components/schemas/Field" } },
                    "recipients": { "type": "array", "items": { "$ref": "#/components/schemas/Recipient" } },
                    "reminders": { "type": "array", "items": { "$ref": "#/components/schemas/Reminder" } }
                  }
                },
                "example": {
                  "companies_workspaces_signing_requests_id": "123e4567-e89b-12d3-a456-426614174000",
                  "fields": [],
                  "recipients": [],
                  "reminders": []
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "Signing request saved successfully",
              "content": {
                "application/json": {
                  "schema": {
                    "type": "object",
                    "properties": {
                      "message": { "type": "string" }
                    }
                  },
                  "example": {
                    "message": "Signing request saved successfully"
                  }
                }
              }
            },
            "400": { "$ref": "#/components/responses/ValidationError" },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "404": { "$ref": "#/components/responses/NotFoundError" }
          }
        }
      },
      "/send-embedded-signing-request": {
        "post": {
          "summary": "Send embedded signing request (JWT authenticated)",
          "description": "Send a signing request to recipients when using embedded editor. Requires JWT authentication obtained from `/jwt/generate-signing-request`. The signing request must have at least one recipient and all required fields must be configured.",
          "tags": ["Signing Requests"],
          "security": [{ "ApiKeyAuth": [] }],
          "requestBody": {
            "required": true,
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["companies_workspaces_signing_requests_id"],
                  "properties": {
                    "companies_workspaces_signing_requests_id": { "type": "string", "format": "uuid", "description": "ID of the signing request to send" }
                  }
                },
                "example": {
                  "companies_workspaces_signing_requests_id": "123e4567-e89b-12d3-a456-426614174000"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "Signing request sent successfully",
              "content": {
                "application/json": {
                  "schema": {
                    "type": "object",
                    "properties": {
                      "message": { "type": "string" },
                      "signing_request_id": { "type": "string", "format": "uuid" }
                    }
                  },
                  "example": {
                    "message": "Signing request sent successfully",
                    "signing_request_id": "123e4567-e89b-12d3-a456-426614174000"
                  }
                }
              }
            },
            "400": { "$ref": "#/components/responses/ValidationError" },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "404": { "$ref": "#/components/responses/NotFoundError" }
          }
        }
      },
      "/get-embedded-signing-request": {
        "post": {
          "summary": "Get embedded signing request data (JWT authenticated)",
          "description": "Retrieve signing request data when using embedded editor. Requires JWT authentication obtained from `/jwt/generate-signing-request`. Returns the complete signing request including fields, recipients, and reminders.",
          "tags": ["Signing Requests"],
          "security": [{ "ApiKeyAuth": [] }],
          "requestBody": {
            "required": true,
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["companies_workspaces_signing_requests_id"],
                  "properties": {
                    "companies_workspaces_signing_requests_id": { "type": "string", "format": "uuid", "description": "ID of the signing request to retrieve" }
                  }
                },
                "example": {
                  "companies_workspaces_signing_requests_id": "123e4567-e89b-12d3-a456-426614174000"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "Signing request retrieved successfully",
              "content": {
                "application/json": {
                  "schema": {
                    "type": "object",
                    "description": "Response uses camelCase keys. The signingRequest is a raw database row (not a formatted object).",
                    "properties": {
                      "signingRequest": { "type": "object", "description": "Raw signing request database row. Field names use database column names (e.g., template_description, document_page_count, created_on, allow_downlaod). Integer flags (0/1) are used instead of booleans." },
                      "fields": { "type": "array", "items": { "$ref": "#/components/schemas/SigningRequestField" }, "description": "Raw field database rows" },
                      "users": { "type": "array", "items": { "$ref": "#/components/schemas/SigningRequestUser" }, "description": "Raw user database rows (note: key is 'users', not 'recipients')" },
                      "reminders": { "type": "array", "items": { "$ref": "#/components/schemas/Reminder" } },
                      "workspace": { "type": "object", "description": "Workspace details", "properties": { "name": { "type": "string" }, "team_email": { "type": "string", "nullable": true }, "icon_url": { "type": "string", "nullable": true }, "timezone": { "type": "string" }, "show_credit_cost_in_editor": { "type": "boolean" }, "require_otp_verification": { "type": "boolean", "nullable": true } } }
                    }
                  }
                }
              }
            },
            "400": { "$ref": "#/components/responses/ValidationError" },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "404": { "$ref": "#/components/responses/NotFoundError" }
          }
        }
      },
      "/workspace/{workspace_id}/email-templates": {
        "get": {
          "summary": "List workspace email templates",
          "description": "Retrieve all custom email templates for a workspace",
          "tags": ["Email Templates"],
          "security": [{ "ApiKeyAuth": [] }],
          "parameters": [
            { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Workspace ID" }
          ],
          "responses": {
            "200": {
              "description": "Email templates retrieved successfully",
              "content": {
                "application/json": {
                  "schema": {
                    "type": "object",
                    "properties": {
                      "results": {
                        "type": "array",
                        "items": { "$ref": "#/components/schemas/EmailTemplate" }
                      },
                      "workspace_id": { "type": "string", "format": "uuid" }
                    }
                  }
                }
              }
            },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        }
      },
      "/workspace/{workspace_id}/email-templates/{email_type}": {
        "get": {
          "summary": "Get workspace email template",
          "description": "Retrieve a specific email template by type for a workspace",
          "tags": ["Email Templates"],
          "security": [{ "ApiKeyAuth": [] }],
          "parameters": [
            { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Workspace ID" },
            { "name": "email_type", "in": "path", "required": true, "schema": { "type": "string", "enum": ["signing_invite", "next_signer", "signing_expired", "signing_cancelled", "signing_declined"] }, "description": "Email template type" }
          ],
          "responses": {
            "200": {
              "description": "Email template retrieved successfully",
              "content": {
                "application/json": {
                  "schema": { "$ref": "#/components/schemas/EmailTemplate" }
                }
              }
            },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "404": { "$ref": "#/components/responses/NotFoundError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        },
        "put": {
          "summary": "Create or update workspace email template",
          "description": "Create or update a custom email template for a specific type. If a template already exists for this type, it will be updated. A warning is returned if the template body does not contain {{signing_link}}.",
          "tags": ["Email Templates"],
          "security": [{ "ApiKeyAuth": [] }],
          "parameters": [
            { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Workspace ID" },
            { "name": "email_type", "in": "path", "required": true, "schema": { "type": "string", "enum": ["signing_invite", "next_signer", "signing_expired", "signing_cancelled", "signing_declined"] }, "description": "Email template type" }
          ],
          "requestBody": {
            "required": true,
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["subject", "body"],
                  "properties": {
                    "subject": { "type": "string", "maxLength": 500, "description": "Email subject line" },
                    "body": { "type": "string", "maxLength": 50000, "description": "Email body (HTML). Use {{signing_link}} placeholder for the signing URL." }
                  }
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "Email template updated successfully",
              "content": {
                "application/json": {
                  "schema": {
                    "allOf": [
                      { "$ref": "#/components/schemas/EmailTemplate" },
                      { "type": "object", "properties": { "warnings": { "type": "array", "items": { "type": "string" } } } }
                    ]
                  }
                }
              }
            },
            "201": {
              "description": "Email template created successfully",
              "content": {
                "application/json": {
                  "schema": {
                    "allOf": [
                      { "$ref": "#/components/schemas/EmailTemplate" },
                      { "type": "object", "properties": { "warnings": { "type": "array", "items": { "type": "string" } } } }
                    ]
                  }
                }
              }
            },
            "400": { "$ref": "#/components/responses/ValidationError" },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        },
        "delete": {
          "summary": "Delete workspace email template",
          "description": "Delete a custom email template. The workspace will revert to using the company-level or default template for this type.",
          "tags": ["Email Templates"],
          "security": [{ "ApiKeyAuth": [] }],
          "parameters": [
            { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Workspace ID" },
            { "name": "email_type", "in": "path", "required": true, "schema": { "type": "string", "enum": ["signing_invite", "next_signer", "signing_expired", "signing_cancelled", "signing_declined"] }, "description": "Email template type" }
          ],
          "responses": {
            "200": {
              "description": "Email template deleted successfully",
              "content": {
                "application/json": {
                  "schema": {
                    "type": "object",
                    "properties": {
                      "message": { "type": "string" },
                      "email_type": { "type": "string" }
                    }
                  }
                }
              }
            },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "404": { "$ref": "#/components/responses/NotFoundError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        }
      },
      "/company/email-templates": {
        "get": {
          "summary": "List company email templates",
          "description": "Retrieve all custom email templates at the company level. Company templates serve as defaults for all workspaces that don't have workspace-specific templates.",
          "tags": ["Email Templates"],
          "security": [{ "ApiKeyAuth": [] }],
          "responses": {
            "200": {
              "description": "Company email templates retrieved successfully",
              "content": {
                "application/json": {
                  "schema": {
                    "type": "object",
                    "properties": {
                      "results": {
                        "type": "array",
                        "items": { "$ref": "#/components/schemas/EmailTemplate" }
                      }
                    }
                  }
                }
              }
            },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        }
      },
      "/company/email-templates/{email_type}": {
        "put": {
          "summary": "Create or update company email template",
          "description": "Create or update a company-level email template for a specific type. Company templates are used as defaults for workspaces without workspace-specific templates.",
          "tags": ["Email Templates"],
          "security": [{ "ApiKeyAuth": [] }],
          "parameters": [
            { "name": "email_type", "in": "path", "required": true, "schema": { "type": "string", "enum": ["signing_invite", "next_signer", "signing_expired", "signing_cancelled", "signing_declined"] }, "description": "Email template type" }
          ],
          "requestBody": {
            "required": true,
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["subject", "body"],
                  "properties": {
                    "subject": { "type": "string", "maxLength": 500, "description": "Email subject line" },
                    "body": { "type": "string", "maxLength": 50000, "description": "Email body (HTML). Use {{signing_link}} placeholder for the signing URL." }
                  }
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "Company email template updated successfully",
              "content": {
                "application/json": {
                  "schema": {
                    "allOf": [
                      { "$ref": "#/components/schemas/EmailTemplate" },
                      { "type": "object", "properties": { "warnings": { "type": "array", "items": { "type": "string" } } } }
                    ]
                  }
                }
              }
            },
            "201": {
              "description": "Company email template created successfully",
              "content": {
                "application/json": {
                  "schema": {
                    "allOf": [
                      { "$ref": "#/components/schemas/EmailTemplate" },
                      { "type": "object", "properties": { "warnings": { "type": "array", "items": { "type": "string" } } } }
                    ]
                  }
                }
              }
            },
            "400": { "$ref": "#/components/responses/ValidationError" },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        },
        "delete": {
          "summary": "Delete company email template",
          "description": "Delete a company-level email template. Workspaces will fall back to the built-in default template for this type.",
          "tags": ["Email Templates"],
          "security": [{ "ApiKeyAuth": [] }],
          "parameters": [
            { "name": "email_type", "in": "path", "required": true, "schema": { "type": "string", "enum": ["signing_invite", "next_signer", "signing_expired", "signing_cancelled", "signing_declined"] }, "description": "Email template type" }
          ],
          "responses": {
            "200": {
              "description": "Company email template deleted successfully",
              "content": {
                "application/json": {
                  "schema": {
                    "type": "object",
                    "properties": {
                      "message": { "type": "string" },
                      "email_type": { "type": "string" }
                    }
                  }
                }
              }
            },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "404": { "$ref": "#/components/responses/NotFoundError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        }
      },
      "/email-templates/defaults/{language}": {
        "get": {
          "summary": "Get default email templates",
          "description": "Retrieve the built-in default email templates for a specific language. These are the templates used when no custom company or workspace templates are configured.",
          "tags": ["Email Templates"],
          "security": [{ "ApiKeyAuth": [] }],
          "parameters": [
            { "name": "language", "in": "path", "required": true, "schema": { "type": "string", "enum": ["en", "es", "it", "pt", "fr", "de", "el"] }, "description": "Language code" }
          ],
          "responses": {
            "200": {
              "description": "Default templates retrieved successfully",
              "content": {
                "application/json": {
                  "schema": {
                    "type": "object",
                    "properties": {
                      "language": { "type": "string" },
                      "templates": {
                        "type": "object",
                        "description": "Map of email_type to default template {subject, body}",
                        "additionalProperties": {
                          "type": "object",
                          "properties": {
                            "subject": { "type": "string" },
                            "body": { "type": "string" }
                          }
                        }
                      }
                    }
                  }
                }
              }
            },
            "400": { "$ref": "#/components/responses/ValidationError" },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        }
      },
      "/email-templates/placeholders": {
        "get": {
          "summary": "Get email template placeholders",
          "description": "Retrieve the list of available placeholders that can be used in email templates. Placeholders are replaced with actual values when emails are sent.",
          "tags": ["Email Templates"],
          "security": [{ "ApiKeyAuth": [] }],
          "responses": {
            "200": {
              "description": "Placeholders retrieved successfully",
              "content": {
                "application/json": {
                  "schema": {
                    "type": "object",
                    "properties": {
                      "placeholders": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "properties": {
                            "key": { "type": "string", "description": "Placeholder key (e.g., 'signing_link')" },
                            "description": { "type": "string", "description": "What this placeholder resolves to" }
                          }
                        }
                      }
                    }
                  }
                }
              }
            },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        }
      },
      "/documents": {
        "post": {
          "summary": "Create document (Legacy)",
          "description": "**DEPRECATED**: Use `/signing-requests` instead. Legacy endpoint for creating a new signing request.",
          "deprecated": true,
          "tags": ["Legacy"],
          "security": [{ "ApiKeyAuth": [] }],
          "requestBody": {
            "required": true,
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["name"],
                  "properties": {
                    "name": { "type": "string", "description": "Document name", "maxLength": 255 },
                    "recipients": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": ["email"],
                        "properties": {
                          "name": { "type": "string" },
                          "email": { "type": "string", "format": "email" }
                        }
                      }
                    }
                  }
                },
                "example": {
                  "name": "Sales Agreement 2024",
                  "recipients": [
                    { "name": "John Doe", "email": "john@example.com" }
                  ]
                }
              }
            }
          },
          "responses": {
            "201": {
              "description": "Document created successfully",
              "headers": {
                "X-Legacy-Endpoint": { "schema": { "type": "string" }, "description": "Indicates this is a legacy endpoint" },
                "X-Deprecated": { "schema": { "type": "string" }, "description": "Deprecation notice" },
                "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Rate limit: 120 requests per minute" },
                "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in current window" },
                "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when rate limit resets" }
              },
              "content": {
                "application/json": {
                  "schema": { "$ref": "#/components/schemas/SigningRequestCreateResponse" }
                }
              }
            },
            "400": { "$ref": "#/components/responses/ValidationError" },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        }
      },
      "/workspace/{workspace_id}/settings": {
        "get": {
          "summary": "Get workspace settings",
          "description": "Retrieve workspace settings",
          "tags": ["Workspace Settings"],
          "security": [{ "ApiKeyAuth": [] }],
          "parameters": [
            { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }
          ],
          "responses": {
            "200": {
              "description": "Workspace settings retrieved successfully",
              "headers": {
                "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Rate limit: 200 requests per minute" },
                "X-RateLimit-Remaining": { "schema": { "type": "integer" } },
                "X-RateLimit-Reset": { "schema": { "type": "integer" } }
              },
              "content": {
                "application/json": {
                  "schema": { "$ref": "#/components/schemas/WorkspaceSettings" }
                }
              }
            },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "404": { "$ref": "#/components/responses/NotFoundError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        },
        "put": {
          "summary": "Update workspace settings",
          "description": "Update workspace settings",
          "tags": ["Workspace Settings"],
          "security": [{ "ApiKeyAuth": [] }],
          "parameters": [
            { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }
          ],
          "requestBody": {
            "required": true,
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "signing_request_email_header": { "type": "string" },
                    "signing_request_email_body": { "type": "string" },
                    "team_email": { "type": "string", "format": "email" },
                    "timezone": { "type": "string" },
                    "language": { "type": "string", "enum": ["en", "es", "it", "pt", "fr", "de", "el"], "description": "Workspace language for email templates" },
                    "show_credit_cost_in_editor": { "type": "boolean", "description": "Whether to display credit cost in embedded editors" },
                    "require_otp_verification": { "type": "boolean", "nullable": true, "description": "Whether signers must verify their email via OTP. null = inherit from company" },
                    "show_signature_frame": { "type": "boolean", "nullable": true, "description": "Whether to render signature frames in completed PDFs. null = inherit from company" }
                  }
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "Workspace settings updated 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": { "$ref": "#/components/schemas/WorkspaceSettings" }
                }
              }
            },
            "400": { "$ref": "#/components/responses/ValidationError" },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "404": { "$ref": "#/components/responses/NotFoundError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        }
      },
      "/workspace/{workspace_id}/domains": {
        "get": {
          "summary": "List workspace domains",
          "description": "List all email domains configured for a specific workspace. These domains are used for sending signing request emails from this workspace.",
          "tags": ["Email Domains"],
          "security": [{ "ApiKeyAuth": [] }],
          "parameters": [
            { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Workspace ID" }
          ],
          "responses": {
            "200": {
              "description": "Workspace domains retrieved successfully",
              "headers": {
                "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Rate limit: 200 requests per minute" },
                "X-RateLimit-Remaining": { "schema": { "type": "integer" } },
                "X-RateLimit-Reset": { "schema": { "type": "integer" } }
              },
              "content": {
                "application/json": {
                  "schema": {
                    "type": "object",
                    "properties": {
                      "results": { "type": "array", "items": { "$ref": "#/components/schemas/Domain" } },
                      "workspace_id": { "type": "string", "format": "uuid", "description": "ID of the workspace" }
                    }
                  },
                  "example": {
                    "results": [
                      {
                        "id": "123e4567-e89b-12d3-a456-426614174000",
                        "domain": "sales.acme.com",
                        "verification_status": 2,
                        "domain_status": 1,
                        "is_primary": true,
                        "date_created": "2024-01-15T10:30:00Z",
                        "date_changed": "2024-01-16T14:00:00Z"
                      }
                    ],
                    "workspace_id": "456e4567-e89b-12d3-a456-426614174000"
                  }
                }
              }
            },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "404": { "$ref": "#/components/responses/NotFoundError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        },
        "post": {
          "summary": "Add workspace domain",
          "description": "Add a new email domain for a specific workspace. This initiates the domain verification process. After creation, you must:\n1. Add a TXT record to your DNS with the verification token\n2. Call POST /workspace/{workspace_id}/domains/{id}/verify-ownership to verify domain ownership\n3. Call POST /workspace/{workspace_id}/domains/{id}/finalize to register with email provider\n4. Add the returned DNS records (SPF, DKIM, etc.)\n5. Call POST /workspace/{workspace_id}/domains/{id}/verify-dns to complete verification",
          "tags": ["Email Domains"],
          "security": [{ "ApiKeyAuth": [] }],
          "parameters": [
            { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Workspace ID" }
          ],
          "requestBody": {
            "required": true,
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["domain"],
                  "properties": {
                    "domain": { "type": "string", "description": "Domain name to add (e.g., 'example.com'). Must be a valid domain format.", "example": "sales.acme.com" }
                  }
                }
              }
            }
          },
          "responses": {
            "201": {
              "description": "Domain created successfully. Add the verification TXT record to your DNS.",
              "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": {
                      "domain": { "$ref": "#/components/schemas/Domain" },
                      "verification_instructions": {
                        "type": "object",
                        "properties": {
                          "record_type": { "type": "string", "example": "TXT" },
                          "record_name": { "type": "string", "example": "_firma-verification.sales.acme.com" },
                          "record_value": { "type": "string", "example": "firma-verify=abc123xyz" },
                          "next_step": { "type": "string", "example": "Add this TXT record to your DNS, then call POST /workspace/{workspace_id}/domains/{id}/verify-ownership" }
                        }
                      }
                    }
                  },
                  "example": {
                    "domain": {
                      "id": "123e4567-e89b-12d3-a456-426614174000",
                      "domain": "sales.acme.com",
                      "verification_status": 0,
                      "domain_status": 0,
                      "is_primary": false,
                      "verification_token": "firma-verify=abc123xyz",
                      "date_created": "2024-01-15T10:30:00Z",
                      "date_changed": "2024-01-15T10:30:00Z"
                    },
                    "verification_instructions": {
                      "record_type": "TXT",
                      "record_name": "_firma-verification.sales.acme.com",
                      "record_value": "firma-verify=abc123xyz",
                      "next_step": "Add this TXT record to your DNS, then call POST /workspace/{workspace_id}/domains/{id}/verify-ownership"
                    }
                  }
                }
              }
            },
            "400": {
              "description": "Invalid domain format or domain already exists",
              "content": {
                "application/json": {
                  "schema": { "$ref": "#/components/schemas/Error" },
                  "examples": {
                    "invalidDomain": {
                      "value": { "error": "Invalid domain format", "message": "Please provide a valid domain name (e.g., example.com)" }
                    },
                    "domainExists": {
                      "value": { "error": "Domain already exists", "message": "This domain is already configured for this workspace" }
                    }
                  }
                }
              }
            },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "404": { "$ref": "#/components/responses/NotFoundError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        }
      },
      "/workspace/{workspace_id}/domains/{id}": {
        "get": {
          "summary": "Get workspace domain",
          "description": "Retrieve details of a specific domain in a workspace including verification status and DNS records",
          "tags": ["Email Domains"],
          "security": [{ "ApiKeyAuth": [] }],
          "parameters": [
            { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Workspace ID" },
            { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Domain ID" }
          ],
          "responses": {
            "200": {
              "description": "Domain retrieved successfully",
              "content": {
                "application/json": {
                  "schema": { "$ref": "#/components/schemas/Domain" }
                }
              }
            },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "404": { "$ref": "#/components/responses/NotFoundError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        },
        "delete": {
          "summary": "Delete workspace domain",
          "description": "Remove a domain from the workspace. Cannot delete the primary domain if it's the only domain.",
          "tags": ["Email Domains"],
          "security": [{ "ApiKeyAuth": [] }],
          "parameters": [
            { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Workspace ID" },
            { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Domain ID" }
          ],
          "responses": {
            "200": {
              "description": "Domain deleted successfully",
              "content": {
                "application/json": {
                  "schema": {
                    "type": "object",
                    "properties": {
                      "message": { "type": "string" },
                      "domain_id": { "type": "string", "format": "uuid" }
                    }
                  },
                  "example": {
                    "message": "Domain deleted successfully",
                    "domain_id": "123e4567-e89b-12d3-a456-426614174000"
                  }
                }
              }
            },
            "400": {
              "description": "Cannot delete primary domain",
              "content": {
                "application/json": {
                  "schema": { "$ref": "#/components/schemas/Error" },
                  "example": { "error": "Cannot delete primary domain", "message": "Set another domain as primary before deleting this one" }
                }
              }
            },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "404": { "$ref": "#/components/responses/NotFoundError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        }
      },
      "/workspace/{workspace_id}/domains/{id}/verify-ownership": {
        "post": {
          "summary": "Verify workspace domain ownership",
          "description": "Verify domain ownership by checking the TXT record. Call this after adding the verification TXT record to your DNS. DNS propagation may take up to 48 hours, but typically completes within minutes.",
          "tags": ["Email Domains"],
          "security": [{ "ApiKeyAuth": [] }],
          "parameters": [
            { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Workspace ID" },
            { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Domain ID" }
          ],
          "responses": {
            "200": {
              "description": "Domain ownership verified successfully",
              "content": {
                "application/json": {
                  "schema": {
                    "type": "object",
                    "properties": {
                      "message": { "type": "string" },
                      "domain": { "$ref": "#/components/schemas/Domain" },
                      "next_step": { "type": "string" }
                    }
                  },
                  "example": {
                    "message": "Domain ownership verified",
                    "domain": {
                      "id": "123e4567-e89b-12d3-a456-426614174000",
                      "domain": "sales.acme.com",
                      "verification_status": 1,
                      "domain_status": 0
                    },
                    "next_step": "Call POST /workspace/{workspace_id}/domains/{id}/finalize to complete domain setup and receive DNS records for email sending"
                  }
                }
              }
            },
            "400": {
              "description": "Verification failed",
              "content": {
                "application/json": {
                  "schema": { "$ref": "#/components/schemas/Error" },
                  "examples": {
                    "recordNotFound": {
                      "value": {
                        "error": "Verification failed",
                        "message": "TXT record not found. Please ensure the record is added correctly and DNS has propagated.",
                        "details": {
                          "expected_record": "_firma-verification.sales.acme.com",
                          "expected_value": "firma-verify=abc123xyz"
                        }
                      }
                    },
                    "alreadyVerified": {
                      "value": { "error": "Already verified", "message": "Domain ownership has already been verified" }
                    }
                  }
                }
              }
            },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "404": { "$ref": "#/components/responses/NotFoundError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        }
      },
      "/workspace/{workspace_id}/domains/{id}/finalize": {
        "post": {
          "summary": "Finalize workspace domain setup",
          "description": "Finalize domain setup by registering with the email provider. This returns the DNS records (SPF, DKIM, DMARC) that must be added to enable email sending. Can only be called after domain ownership is verified.",
          "tags": ["Email Domains"],
          "security": [{ "ApiKeyAuth": [] }],
          "parameters": [
            { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Workspace ID" },
            { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Domain ID" }
          ],
          "responses": {
            "200": {
              "description": "Domain finalized successfully. Add the returned DNS records.",
              "content": {
                "application/json": {
                  "schema": {
                    "type": "object",
                    "properties": {
                      "message": { "type": "string" },
                      "domain": { "$ref": "#/components/schemas/Domain" },
                      "dns_records": {
                        "type": "array",
                        "items": { "$ref": "#/components/schemas/DomainDnsRecord" },
                        "description": "DNS records to add for email sending"
                      },
                      "next_step": { "type": "string" }
                    }
                  },
                  "example": {
                    "message": "Domain finalized. Add the following DNS records to enable email sending.",
                    "domain": {
                      "id": "123e4567-e89b-12d3-a456-426614174000",
                      "domain": "sales.acme.com",
                      "verification_status": 2,
                      "domain_status": 0
                    },
                    "dns_records": [
                      { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "ttl": "Auto", "status": "pending" },
                      { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "ttl": "Auto", "status": "pending" },
                      { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "ttl": "Auto", "status": "pending" }
                    ],
                    "next_step": "Add these DNS records, then call POST /workspace/{workspace_id}/domains/{id}/verify-dns to complete verification"
                  }
                }
              }
            },
            "400": {
              "description": "Cannot finalize",
              "content": {
                "application/json": {
                  "schema": { "$ref": "#/components/schemas/Error" },
                  "examples": {
                    "notVerified": {
                      "value": { "error": "Ownership not verified", "message": "Please verify domain ownership first by calling POST /workspace/{workspace_id}/domains/{id}/verify-ownership" }
                    },
                    "alreadyFinalized": {
                      "value": { "error": "Already finalized", "message": "Domain has already been finalized" }
                    }
                  }
                }
              }
            },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "404": { "$ref": "#/components/responses/NotFoundError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        }
      },
      "/workspace/{workspace_id}/domains/{id}/verify-dns": {
        "post": {
          "summary": "Verify workspace domain DNS records",
          "description": "Verify that all required DNS records (SPF, DKIM, DMARC) are properly configured. Call this after adding all DNS records from the finalize step. Once verified, the domain is ready for sending emails.",
          "tags": ["Email Domains"],
          "security": [{ "ApiKeyAuth": [] }],
          "parameters": [
            { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Workspace ID" },
            { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Domain ID" }
          ],
          "responses": {
            "200": {
              "description": "DNS verification result",
              "content": {
                "application/json": {
                  "schema": {
                    "type": "object",
                    "properties": {
                      "verified": { "type": "boolean", "description": "Whether all DNS records are verified" },
                      "message": { "type": "string" },
                      "domain": { "$ref": "#/components/schemas/Domain" },
                      "dns_records": {
                        "type": "array",
                        "items": { "$ref": "#/components/schemas/DomainDnsRecord" },
                        "description": "Status of each DNS record"
                      }
                    }
                  },
                  "examples": {
                    "verified": {
                      "summary": "All records verified",
                      "value": {
                        "verified": true,
                        "message": "Domain is fully verified and ready to send emails",
                        "domain": {
                          "id": "123e4567-e89b-12d3-a456-426614174000",
                          "domain": "sales.acme.com",
                          "verification_status": 2,
                          "domain_status": 1,
                          "is_primary": true
                        },
                        "dns_records": [
                          { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "status": "verified" },
                          { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "status": "verified" },
                          { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "status": "verified" }
                        ]
                      }
                    },
                    "pending": {
                      "summary": "Some records pending",
                      "value": {
                        "verified": false,
                        "message": "Some DNS records are not yet verified. Please check your DNS configuration.",
                        "domain": {
                          "id": "123e4567-e89b-12d3-a456-426614174000",
                          "domain": "sales.acme.com",
                          "verification_status": 2,
                          "domain_status": 0
                        },
                        "dns_records": [
                          { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "status": "verified" },
                          { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "status": "pending" },
                          { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "status": "pending" }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "description": "Domain not finalized",
              "content": {
                "application/json": {
                  "schema": { "$ref": "#/components/schemas/Error" },
                  "example": { "error": "Domain not finalized", "message": "Please finalize domain setup first by calling POST /workspace/{workspace_id}/domains/{id}/finalize" }
                }
              }
            },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "404": { "$ref": "#/components/responses/NotFoundError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        }
      },
      "/workspace/{workspace_id}/domains/{id}/set-primary": {
        "post": {
          "summary": "Set primary workspace domain",
          "description": "Set a domain as the primary sending domain for the workspace. Only fully verified domains (domain_status=1) can be set as primary.",
          "tags": ["Email Domains"],
          "security": [{ "ApiKeyAuth": [] }],
          "parameters": [
            { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Workspace ID" },
            { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Domain ID" }
          ],
          "responses": {
            "200": {
              "description": "Primary domain updated successfully",
              "content": {
                "application/json": {
                  "schema": {
                    "type": "object",
                    "properties": {
                      "message": { "type": "string" },
                      "domain": { "$ref": "#/components/schemas/Domain" }
                    }
                  },
                  "example": {
                    "message": "Primary domain updated",
                    "domain": {
                      "id": "123e4567-e89b-12d3-a456-426614174000",
                      "domain": "sales.acme.com",
                      "verification_status": 2,
                      "domain_status": 1,
                      "is_primary": true
                    }
                  }
                }
              }
            },
            "400": {
              "description": "Domain not verified",
              "content": {
                "application/json": {
                  "schema": { "$ref": "#/components/schemas/Error" },
                  "example": { "error": "Domain not verified", "message": "Only fully verified domains can be set as primary" }
                }
              }
            },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "404": { "$ref": "#/components/responses/NotFoundError" },
            "429": { "$ref": "#/components/responses/RateLimitError" }
          }
        }
      },
      "/workspace/{workspace_id}/custom-fields": {
        "get": {
          "summary": "List workspace custom fields",
          "description": "Get all custom field definitions for a workspace",
          "tags": ["Custom Fields"],
          "security": [{ "ApiKeyAuth": [] }],
          "parameters": [
            { "name": "workspace_id", "in": "path", "required": true, "description": "Workspace ID", "schema": { "type": "string", "format": "uuid" } }
          ],
          "responses": {
            "200": {
              "description": "Custom fields retrieved successfully",
              "content": {
                "application/json": {
                  "schema": {
                    "type": "object",
                    "properties": {
                      "custom_fields": {
                        "type": "array",
                        "items": { "$ref": "#/components/schemas/WorkspaceCustomField" }
                      }
                    }
                  }
                }
              }
            },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "404": { "$ref": "#/components/responses/NotFoundError" }
          }
        },
        "post": {
          "summary": "Create workspace custom field",
          "description": "Create a new custom field definition for a workspace",
          "tags": ["Custom Fields"],
          "security": [{ "ApiKeyAuth": [] }],
          "parameters": [
            { "name": "workspace_id", "in": "path", "required": true, "description": "Workspace ID", "schema": { "type": "string", "format": "uuid" } }
          ],
          "requestBody": {
            "required": true,
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["field_label"],
                  "properties": {
                    "field_label": { "type": "string", "description": "Display label (1-100 characters)", "maxLength": 100 },
                    "field_name": { "type": "string", "description": "Optional machine-readable name (auto-generated from label if not provided)", "maxLength": 50 },
                    "is_preset": { "type": "boolean", "description": "If true, field has a preset value for all users", "default": false },
                    "preset_value": { "type": "string", "description": "Preset value (max 500 characters, only used when is_preset=true)", "maxLength": 500 }
                  }
                }
              }
            }
          },
          "responses": {
            "201": {
              "description": "Custom field created successfully",
              "content": {
                "application/json": {
                  "schema": { "$ref": "#/components/schemas/WorkspaceCustomField" }
                }
              }
            },
            "400": { "$ref": "#/components/responses/ValidationError" },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "409": {
              "description": "Conflict - A custom field with this name already exists",
              "content": {
                "application/json": {
                  "schema": { "$ref": "#/components/schemas/Error" }
                }
              }
            }
          }
        }
      },
      "/workspace/{workspace_id}/custom-fields/{field_id}": {
        "put": {
          "summary": "Update workspace custom field",
          "description": "Update an existing custom field definition",
          "tags": ["Custom Fields"],
          "security": [{ "ApiKeyAuth": [] }],
          "parameters": [
            { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } },
            { "name": "field_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }
          ],
          "requestBody": {
            "required": true,
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "field_label": { "type": "string", "maxLength": 100 },
                    "is_preset": { "type": "boolean" },
                    "preset_value": { "type": "string", "maxLength": 500 }
                  }
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "Custom field updated successfully",
              "content": {
                "application/json": {
                  "schema": { "$ref": "#/components/schemas/WorkspaceCustomField" }
                }
              }
            },
            "400": { "$ref": "#/components/responses/ValidationError" },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "404": { "$ref": "#/components/responses/NotFoundError" },
            "409": {
              "description": "Conflict - A custom field with this name already exists",
              "content": {
                "application/json": {
                  "schema": { "$ref": "#/components/schemas/Error" }
                }
              }
            }
          }
        },
        "delete": {
          "summary": "Delete workspace custom field",
          "description": "Soft-delete a custom field definition",
          "tags": ["Custom Fields"],
          "security": [{ "ApiKeyAuth": [] }],
          "parameters": [
            { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } },
            { "name": "field_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }
          ],
          "responses": {
            "200": {
              "description": "Custom field deleted successfully",
              "content": {
                "application/json": {
                  "schema": {
                    "type": "object",
                    "properties": {
                      "message": { "type": "string", "example": "Custom field deleted successfully" }
                    }
                  }
                }
              }
            },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "404": { "$ref": "#/components/responses/NotFoundError" }
          }
        }
      },
      "/templates/{template_id}/custom-fields": {
        "get": {
          "summary": "List template custom fields",
          "description": "Get all custom field definitions for a template",
          "tags": ["Custom Fields"],
          "security": [{ "ApiKeyAuth": [] }],
          "parameters": [
            { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }
          ],
          "responses": {
            "200": {
              "description": "Custom fields retrieved successfully",
              "content": {
                "application/json": {
                  "schema": {
                    "type": "object",
                    "properties": {
                      "custom_fields": {
                        "type": "array",
                        "items": { "$ref": "#/components/schemas/TemplateCustomField" }
                      }
                    }
                  }
                }
              }
            },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "404": { "$ref": "#/components/responses/NotFoundError" }
          }
        },
        "post": {
          "summary": "Create template custom field",
          "description": "Create a new custom field definition for a template",
          "tags": ["Custom Fields"],
          "security": [{ "ApiKeyAuth": [] }],
          "parameters": [
            { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }
          ],
          "requestBody": {
            "required": true,
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["field_label"],
                  "properties": {
                    "field_label": { "type": "string", "maxLength": 100 },
                    "field_name": { "type": "string", "maxLength": 50 }
                  }
                }
              }
            }
          },
          "responses": {
            "201": {
              "description": "Custom field created successfully",
              "content": {
                "application/json": {
                  "schema": { "$ref": "#/components/schemas/TemplateCustomField" }
                }
              }
            },
            "400": { "$ref": "#/components/responses/ValidationError" },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "404": { "$ref": "#/components/responses/NotFoundError" },
            "409": {
              "description": "Conflict - A custom field with this name already exists",
              "content": {
                "application/json": {
                  "schema": { "$ref": "#/components/schemas/Error" }
                }
              }
            }
          }
        }
      },
      "/templates/{template_id}/custom-fields/{field_id}": {
        "delete": {
          "summary": "Delete template custom field",
          "description": "Soft-delete a custom field definition from a template",
          "tags": ["Custom Fields"],
          "security": [{ "ApiKeyAuth": [] }],
          "parameters": [
            { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } },
            { "name": "field_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }
          ],
          "responses": {
            "200": {
              "description": "Custom field deleted successfully",
              "content": {
                "application/json": {
                  "schema": {
                    "type": "object",
                    "properties": {
                      "message": { "type": "string", "example": "Custom field deleted successfully" }
                    }
                  }
                }
              }
            },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "404": { "$ref": "#/components/responses/NotFoundError" }
          }
        }
      },
      "/signing-requests/{request_id}/custom-fields": {
        "get": {
          "summary": "List signing request custom fields",
          "description": "Get all custom field definitions for a signing request",
          "tags": ["Custom Fields"],
          "security": [{ "ApiKeyAuth": [] }],
          "parameters": [
            { "name": "request_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }
          ],
          "responses": {
            "200": {
              "description": "Custom fields retrieved successfully",
              "content": {
                "application/json": {
                  "schema": {
                    "type": "object",
                    "properties": {
                      "custom_fields": {
                        "type": "array",
                        "items": { "$ref": "#/components/schemas/SigningRequestCustomField" }
                      }
                    }
                  }
                }
              }
            },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "404": { "$ref": "#/components/responses/NotFoundError" }
          }
        },
        "post": {
          "summary": "Create signing request custom field",
          "description": "Create a new custom field definition for a signing request",
          "tags": ["Custom Fields"],
          "security": [{ "ApiKeyAuth": [] }],
          "parameters": [
            { "name": "request_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }
          ],
          "requestBody": {
            "required": true,
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["field_label"],
                  "properties": {
                    "field_label": { "type": "string", "maxLength": 100 },
                    "field_name": { "type": "string", "maxLength": 50 }
                  }
                }
              }
            }
          },
          "responses": {
            "201": {
              "description": "Custom field created successfully",
              "content": {
                "application/json": {
                  "schema": { "$ref": "#/components/schemas/SigningRequestCustomField" }
                }
              }
            },
            "400": { "$ref": "#/components/responses/ValidationError" },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "404": { "$ref": "#/components/responses/NotFoundError" },
            "409": {
              "description": "Conflict - A custom field with this name already exists",
              "content": {
                "application/json": {
                  "schema": { "$ref": "#/components/schemas/Error" }
                }
              }
            }
          }
        }
      },
      "/signing-requests/{request_id}/custom-fields/{field_id}": {
        "delete": {
          "summary": "Delete signing request custom field",
          "description": "Soft-delete a custom field definition from a signing request",
          "tags": ["Custom Fields"],
          "security": [{ "ApiKeyAuth": [] }],
          "parameters": [
            { "name": "request_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } },
            { "name": "field_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }
          ],
          "responses": {
            "200": {
              "description": "Custom field deleted successfully",
              "content": {
                "application/json": {
                  "schema": {
                    "type": "object",
                    "properties": {
                      "message": { "type": "string", "example": "Custom field deleted successfully" }
                    }
                  }
                }
              }
            },
            "401": { "$ref": "#/components/responses/UnauthorizedError" },
            "404": { "$ref": "#/components/responses/NotFoundError" }
          }
        }
      }
    }
  }