openapi: 3.2.0 info: title: Firma Partner Signing Requests API description: RESTful API for document signing and template management. version: 01.38.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: Signing Requests description: Document signing request operations paths: /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. **Available statuses:** - `not_sent`: Request created but not yet sent to signers - `in_progress`: Sent to signers but not completed, cancelled, declined, or expired - `finished`: All signers have completed - `cancelled`: Request was cancelled by sender - `declined`: A signer declined to sign (request stopped) - `deleted`: Soft-deleted records (normally hidden) - `expired`: Sent but past expiration time (sent_on + expiration_hours < now) **Example:** `?status=in_progress,expired` **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: $ref: '#/components/schemas/SigningRequestListResponse' '401': $ref: '#/components/responses/UnauthorizedError' '429': $ref: '#/components/responses/RateLimitError' operationId: listSigningRequests x-codeSamples: - lang: TypeScript label: '@firma-dev/sdk' source: 'import { FirmaClient } from "@firma-dev/sdk"; const firma = new FirmaClient({ apiKey: "YOUR_API_KEY" }); const response = await firma.signingRequests.listSigningRequests(); console.log(response);' 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. **Temporary ID Pattern**: For document-based creation, you can reference recipients before they''re created using temporary IDs (format: ''temp_X'' where X is any identifier, e.g., ''temp_1'', ''temp_alice''). Use these temporary IDs in recipient.id, field.recipient_id, and reminder.recipient_id. The API validates all references and automatically maps temporary IDs to real UUIDs after recipients are created. The response contains only real UUIDs. **Temporary ID Validation**: Temporary IDs must start with ''temp_'', be unique across all recipients in the request, and all field/reminder references must point to recipients defined in the same request. Invalid format, duplicate IDs, or missing recipient references return a 400 error with detailed validation messages.' tags: - Signing Requests security: - ApiKeyAuth: [] requestBody: required: true content: application/json: schema: 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. For documents larger than 5 MB, use POST /documents and pass the document_id instead. name: type: string maxLength: 255 description: Name for the signing request description: type: string description: Description for the signing request expiration_hours: type: integer minimum: 1 default: 168 description: 'Hours until the signing request expires (default: 168 = 7 days)' recipients: type: array items: $ref: '#/components/schemas/Recipient' description: Recipients for the signing request. Use temporary IDs (e.g., 'temp_1') in the id field to reference recipients in fields/reminders. fields: type: array items: $ref: '#/components/schemas/Field' description: Fields to place on the document. Use recipient_id to assign fields to recipients. anchor_tags: type: array maxItems: 100 items: $ref: '#/components/schemas/AnchorTag' description: Anchor tags for automatic field placement. Text markers in the PDF are located and converted to positioned fields. The anchor text is removed from the PDF after processing. Fields created from anchor tags are added alongside any manually specified fields. Only available for document-based creation (not template-based). reminders: type: array items: $ref: '#/components/schemas/SigningRequestReminder' description: Reminders to send to recipients settings: $ref: '#/components/schemas/SigningRequestSettings' description: Signing request settings language: type: - string - 'null' enum: - en - es - it - pt - fr - de - el - ru - pl - cs - sv - nl - ro - nb - ca description: Opt-in email language for this signing request. When set, all signer-facing emails (and their date formatting) use it. Omit or null to fall back to the workspace, then company, default language (unchanged behavior). completion_title: type: - string - 'null' description: Heading shown on the completion page after signing. Inherits from the workspace, then the company, when omitted or null. maxLength: 200 completion_message: type: - string - 'null' description: Body text shown on the completion page after signing. Inherits from the workspace, then the company, when omitted or null. maxLength: 1000 completion_redirect_url: type: - string - 'null' format: uri description: URL the signer is redirected to from the completion page. Must use https:// (http://localhost and http://127.0.0.1 are also accepted on test-mode signing requests). Inherits from the workspace, then the company, when omitted or null. maxLength: 2000 completion_redirect_delay: type: - integer - 'null' description: Seconds the completion page waits before redirecting (0 redirects immediately). Only applies when a redirect URL resolves; the page falls back to 5 seconds when no level sets a delay. Inherits from the workspace, then the company, when omitted or null. minimum: 0 maximum: 30 seal_participants: type: array items: $ref: '#/components/schemas/SealParticipantInput' description: Organization seal participants to include in the signing sequence - 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. Recipients with designation CC are never matched to template users; they are added as CC recipients. The template's CC recipients are copied to the signing request, skipping any whose email (case-insensitive) is already on a CC recipient of the request. 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 language: type: - string - 'null' enum: - en - es - it - pt - fr - de - el - ru - pl - cs - sv - nl - ro - nb - ca description: Opt-in email language for this signing request. When set, all signer-facing emails (and their date formatting) use it. Omit or null to fall back to the workspace, then company, default language (unchanged behavior). completion_title: type: - string - 'null' description: Heading shown on the completion page after signing. Falls back to the template value, then the workspace and company defaults, when omitted or null. maxLength: 200 completion_message: type: - string - 'null' description: Body text shown on the completion page after signing. Falls back to the template value, then the workspace and company defaults, when omitted or null. maxLength: 1000 completion_redirect_url: type: - string - 'null' format: uri description: URL the signer is redirected to from the completion page. Must use https:// (http://localhost and http://127.0.0.1 are also accepted on test-mode signing requests). Falls back to the template value, then the workspace and company defaults, when omitted or null. maxLength: 2000 completion_redirect_delay: type: - integer - 'null' description: Seconds the completion page waits before redirecting (0 redirects immediately). Only applies when a redirect URL resolves; the page falls back to 5 seconds when no level sets a delay. Falls back to the template value, then the workspace and company defaults, when omitted or null. minimum: 0 maximum: 30 seal_participants: type: array items: $ref: '#/components/schemas/SealParticipantInput' description: Organization seal participants to include in the signing sequence 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 properties: seal_participants: type: array items: $ref: '#/components/schemas/SealParticipantInput' description: Organization seal participants to include in the signing sequence fields: type: array items: allOf: - $ref: '#/components/schemas/Field' - type: object properties: seal_participant_temp_id: type: string description: Temporary ID of the seal participant this field is assigned to (matches temp_id in seal_participants array) properties: seal_participant_temp_id: type: string description: Temporary ID of the seal participant this field is assigned to (matches temp_id in seal_participants array) description: Fields to place on the document 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 responses: '201': description: Signing request created successfully. The response may include non-blocking email or anchor-tag warnings. 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 6MB request payload (~4.5MB raw). 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' '503': description: Anchor-tag processing is disabled on the edge fallback. Retry through the primary API route. content: application/json: schema: type: object required: - error - code properties: error: type: string code: type: string enum: - ANCHOR_DISABLED_EDGE '429': $ref: '#/components/responses/RateLimitError' operationId: createSigningRequest x-codeSamples: - lang: TypeScript label: '@firma-dev/sdk' source: "import { FirmaClient } from \"@firma-dev/sdk\";\n\nconst firma = new FirmaClient({ apiKey: \"YOUR_API_KEY\" });\n\nconst response = await firma.signingRequests.createSigningRequest({\n template_id: \"template_id\",\n name: \"Updated Contract Name\",\n expiration_hours: 72\n});\nconsole.log(response);" /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. **Key Benefits:** - Single API call instead of two separate requests - Validates all send requirements BEFORE creating the signing request - Atomic credit deduction - only charges if everything succeeds - Returns status: ''sent'' immediately with first signer details - More efficient (saves 1 API call + round-trip time) **Validation:** - All standard creation validations (document/template, recipients, fields) - Additional send validations: - All signers must have first_name and valid email - Required read-only fields must have final_value populated - Prefilled data fields (variable_name) must have corresponding user data - Company must have sufficient credits (≥1) **Atomicity:** - If any validation fails, nothing is created - Credit is only deducted after successful creation and before email send - If email send fails after creation, signing request remains in ''draft'' status and credit is NOT deducted **Temporary ID Pattern:** For document-based creation, use temporary IDs (format: ''temp_X'') to reference recipients before creation. The API validates all references and automatically maps temporary IDs to real UUIDs. **Rate Limit:** 120 requests/minute (same as write operations)' 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 and document_id). DOCX files are automatically converted to PDF. For documents larger than 5 MB, use POST /documents and pass the document_id instead. example: JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXBlIC9QYWdlCi9QYXJlbnQgMSAwIFIKL1Jlc291c... template_id: type: string format: uuid description: Template ID to use (mutually exclusive with document and document_id) 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. Recipients with designation CC are never matched to template users; they are added as CC recipients. The template''s CC recipients are copied to the signing request, skipping any whose email (case-insensitive) is already on a CC recipient of the request.' minItems: 1 items: $ref: '#/components/schemas/Recipient' fields: type: array description: Array of fields to be filled (document-based only) items: type: object required: - type - page - x - y properties: recipient_id: type: string description: Temporary ID or UUID of recipient assigned to this field example: temp_signer_1 type: type: string enum: - signature - initial - text - date - checkbox - dropdown - radio_buttons - text_area - url - file - stamp - approval_signature - approval_checkmark - approval_date description: 'Field type. Accepts aliases: "initials" (normalized to "initial"), "textarea" (normalized to "text_area"), "radio" (normalized to "radio_buttons").' example: signature page: type: integer minimum: 1 description: PDF page number (1-indexed) example: 1 x: type: number description: X coordinate on page example: 100 y: type: number description: Y coordinate on page example: 200 width: type: number default: 200 example: 200 height: type: number default: 50 example: 50 variable_name: type: string description: Variable name for prefilled data (e.g., 'phone_number', 'company'). If set, the corresponding recipient field must be populated. enum: - first_name - last_name - full_name - email - phone_number - street_address - city - state_province - postal_code - country - title - company example: phone_number variable_defined_name: type: - string - 'null' maxLength: 100 description: Human-readable custom field definition name. Can be used as an alternative to variable_name for targeting fields in template-based creation. required: type: boolean default: false description: Whether field is required read_only: type: boolean default: false description: Whether field is read-only (pre-filled) final_value: type: string description: Pre-filled value for read-only fields (required if read_only=true and required=true) example: Software Engineer background_color: type: - string - 'null' pattern: ^#([0-9A-Fa-f]{3}|[0-9A-Fa-f]{6})$ description: Background color as hex (e.g., '#FFFDE7') example: '#FFFDE7' dropdown_options: description: Options for dropdown fields. Required when type is "dropdown". example: - Option A - Option B - Option C oneOf: - type: array items: type: string - type: object seal_participant_temp_id: type: string description: Temporary ID of the seal participant this field is assigned to (matches temp_id in seal_participants array) anchor_tags: type: array maxItems: 100 items: $ref: '#/components/schemas/AnchorTag' description: Anchor tags for automatic field placement. Text markers in the PDF are located and converted to positioned fields. The anchor text is removed from the PDF after processing. Fields created from anchor tags are added alongside any manually specified fields. Only available for document-based creation (not template-based). reminders: type: array description: Array of reminder configurations items: type: object required: - hours_before_expiration properties: hours_before_expiration: type: integer minimum: 1 description: Hours before expiration to send reminder example: 24 settings: type: object description: Signing request settings properties: use_signing_order: type: boolean default: true description: Enforce signing order based on recipient.order. When false, all signers receive the document simultaneously. allow_download: type: boolean default: true description: Allow recipients to download document attach_pdf_on_finish: type: boolean default: true description: Attach completed PDF to completion email send_signing_email: type: boolean default: true description: Send email notification to signers send_finish_email: type: boolean default: true description: Send email when all signatures complete send_expiration_email: type: boolean default: true description: Send email when request expires send_cancellation_email: type: boolean default: true description: Send email when request is cancelled hand_drawn_only: type: boolean default: false description: Require signers to hand-draw their signatures instead of using typed signatures identity_editable_fields: type: - array - 'null' items: type: string enum: - name - company - title - phone - address description: Identity fields signers can edit before signing. null = disabled. When set, a confirmation dialog appears allowing signers to edit the specified fields. example: - name - company notify_identity_change_webhook: type: boolean default: false description: Send webhook event when a signer changes their identity notify_identity_change_email: type: boolean default: false description: Send email notification when a signer changes their identity document_id: type: string format: uuid description: ID of a previously uploaded document (mutually exclusive with document and template_id). Obtain by calling POST /documents first. example: 123e4567-e89b-12d3-a456-426614174000 language: type: - string - 'null' enum: - en - es - it - pt - fr - de - el - ru - pl - cs - sv - nl - ro - nb - ca description: Opt-in email language for this signing request. When set, all signer-facing emails (and their date formatting) use it. Omit or null to fall back to the workspace, then company, default language (unchanged behavior). completion_title: type: - string - 'null' description: Heading shown on the completion page after signing. Falls back to the template value (when template_id is used), then the workspace and company defaults. example: Thank you for signing maxLength: 200 completion_message: type: - string - 'null' description: Body text shown on the completion page after signing. Falls back to the template value (when template_id is used), then the workspace and company defaults. example: Your signed copy is on its way to your inbox. maxLength: 1000 completion_redirect_url: type: - string - 'null' format: uri description: URL the signer is redirected to from the completion page. Must use https:// (http://localhost and http://127.0.0.1 are also accepted on test-mode signing requests). Falls back to the template value (when template_id is used), then the workspace and company defaults. example: https://example.com/thank-you maxLength: 2000 completion_redirect_delay: type: - integer - 'null' description: Seconds the completion page waits before redirecting (0 redirects immediately). Only applies when a redirect URL resolves; the page falls back to 5 seconds when no level sets a delay. Falls back to the template value (when template_id is used), then the workspace and company defaults. example: 5 minimum: 0 maximum: 30 seal_participants: type: array items: $ref: '#/components/schemas/SealParticipantInput' description: Organization seal participants to include in the signing sequence oneOf: - required: - document - required: - template_id examples: document-based: summary: Create and send with document value: name: Employment Contract - John Doe description: Full-time employment contract document: JVBERi0xLjQKJeLjz9MK... expiration_hours: 168 recipients: - id: temp_signer_1 first_name: John last_name: Doe email: john.doe@example.com designation: Signer order: 1 phone_number: +1-555-0123 company: Acme Corp title: Software Engineer fields: - recipient_id: temp_signer_1 type: signature page: 1 x: 100 y: 500 width: 200 height: 50 - recipient_id: temp_signer_1 type: text page: 1 x: 100 y: 400 width: 150 height: 30 variable_name: phone_number required: true read_only: true settings: use_signing_order: true send_signing_email: true template-based: summary: Create and send from template value: name: NDA - Jane Smith template_id: 123e4567-e89b-12d3-a456-426614174000 recipients: - first_name: Jane last_name: Smith email: jane.smith@example.com designation: Signer order: 1 company: Tech Startup Inc expiration_hours: 72 responses: '201': description: Signing request created and sent successfully. The response may include non-blocking anchor-tag warnings. 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/CreateAndSendResponse' example: id: 550e8400-e29b-41d4-a716-446655440000 name: Employment Contract - John Doe description: Full-time employment contract status: sent document_url: https://storage.supabase.co/... page_count: 3 expiration_hours: 168 settings: use_signing_order: true allow_download: true attach_pdf_on_finish: true send_signing_email: true send_finish_email: true send_expiration_email: true send_cancellation_email: true hand_drawn_only: false created_date: '2026-01-12T10:30:00Z' sent_date: '2026-01-12T10:30:00Z' template_id: null first_signer: id: rec456-e89b-12d3-a456-426614174000 name: John Doe email: john.doe@example.com signing_link: https://app.firma.dev/signing/rec456-e89b-12d3-a456-426614174000 recipients: - id: rec456-e89b-12d3-a456-426614174000 first_name: John last_name: Doe name: John Doe email: john.doe@example.com designation: Signer order: 1 fields: - id: field123-e89b-12d3-a456-426614174000 type: signature page: 1 x: 100 y: 500 width: 200 height: 50 required: true recipient_id: rec456-e89b-12d3-a456-426614174000 credits_remaining: 99 '400': description: Validation error - invalid input or missing required signer data content: application/json: schema: $ref: '#/components/schemas/CreateAndSendValidationError' 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: $ref: '#/components/schemas/InsufficientCreditsError' '404': description: Template not found or does not belong to workspace content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: Anchor-tag processing is disabled on the edge fallback. Retry through the primary API route. content: application/json: schema: type: object required: - error - code properties: error: type: string code: type: string enum: - ANCHOR_DISABLED_EDGE '422': description: Recipient email address is suppressed (previously bounced or marked as spam) and cannot be sent to content: application/json: schema: $ref: '#/components/schemas/UnprocessableEntityError' '429': $ref: '#/components/responses/RateLimitError' '500': description: Unexpected server error. Any partially-created signing request is rolled back, so no draft is left behind. Client-actionable send-step failures return 400, 402, or 422 instead. content: application/json: schema: $ref: '#/components/schemas/Error' operationId: createAndSendSigningRequest x-codeSamples: - lang: TypeScript label: '@firma-dev/sdk' source: "import { FirmaClient } from \"@firma-dev/sdk\";\n\nconst firma = new FirmaClient({ apiKey: \"YOUR_API_KEY\" });\n\nconst response = await firma.signingRequests.createAndSendSigningRequest({\n \"name\": \"Employment Contract - John Doe\",\n \"description\": \"Full-time employment contract\",\n \"document\": \"JVBERi0xLjQKJeLjz9MK...\",\n \"expiration_hours\": 168,\n \"recipients\": [\n {\n \"id\": \"temp_signer_1\",\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"email\": \"john.doe@example.com\",\n \"designation\": \"Signer\",\n \"order\": 1,\n \"phone_number\": \"+1-555-0123\",\n \"company\": \"Acme Corp\",\n \"title\": \"Software Engineer\"\n }\n ],\n \"fields\": [\n {\n \"recipient_id\": \"temp_signer_1\",\n \"type\": \"signature\",\n \"page\": 1,\n \"x\": 100,\n \"y\": 500,\n \"width\": 200,\n \"height\": 50\n },\n {\n \"recipient_id\": \"temp_signer_1\",\n \"type\": \"text\",\n \"page\": 1,\n \"x\": 100,\n \"y\": 400,\n \"width\": 150,\n \"height\": 30,\n \"variable_name\": \"phone_number\",\n \"required\": true,\n \"read_only\": true\n }\n ],\n \"settings\": {\n \"use_signing_order\": true,\n \"send_signing_email\": true\n }\n});\nconsole.log(response);" /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' operationId: getSigningRequest x-codeSamples: - lang: TypeScript label: '@firma-dev/sdk' source: "import { FirmaClient } from \"@firma-dev/sdk\";\n\nconst firma = new FirmaClient({ apiKey: \"YOUR_API_KEY\" });\n\nconst response = await firma.signingRequests.getSigningRequest({\n id: \"id\"\n});\nconsole.log(response);" 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 language: type: - string - 'null' enum: - en - es - it - pt - fr - de - el - ru - pl - cs - sv - nl - ro - nb - ca description: Opt-in email language for this signing request. When set, all signer-facing emails (and their date formatting) use it. Omit or null to fall back to the workspace, then company, default language (unchanged behavior). completion_title: type: - string - 'null' description: Heading shown on the completion page after signing. Null or an empty string clears the override; omitted leaves it unchanged. maxLength: 200 completion_message: type: - string - 'null' description: Body text shown on the completion page after signing. Null or an empty string clears the override; omitted leaves it unchanged. maxLength: 1000 completion_redirect_url: type: - string - 'null' format: uri description: URL the signer is redirected to from the completion page. Must use https:// (http://localhost and http://127.0.0.1 are also accepted on test-mode signing requests). Null or an empty string clears the override; omitted leaves it unchanged. maxLength: 2000 completion_redirect_delay: type: - integer - 'null' description: Seconds the completion page waits before redirecting (0 redirects immediately). Only applies when a redirect URL resolves; the page falls back to 5 seconds when no level sets a delay. Null clears the override; omitted leaves it unchanged. minimum: 0 maximum: 30 - 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 - file - stamp - approval_signature - approval_checkmark - approval_date description: Field type. Accepts 'initial' or 'initials', 'textarea' or 'text_area'. Required for new fields. url fields are automatically read-only. file fields allow signers to upload attachments (images/PDF). stamp fields display a pre-configured image. 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 - 'null' format: uuid description: Recipient ID to assign field to variable_name: type: string description: Variable name for prefilled data mapping variable_defined_name: type: - string - 'null' maxLength: 100 description: Human-readable custom field definition name. Can be used as an alternative to variable_name for targeting fields in template-based creation. dropdown_options: description: Options for dropdown fields oneOf: - type: array items: type: string - type: object format_rules: type: object description: Format rules (e.g., date format, urlDisplayText for url fields, acceptedFileTypes for file 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) - type: object required: - seal_participant description: Swap or assign a seal participant on a sent signing request. The seal_participant object identifies the participant slot and the target seal to apply. properties: seal_participant: type: object required: - participant_id - swap_to_seal_id description: Seal participant swap. Replaces the seal assigned to a participant slot with a different seal. properties: participant_id: type: string format: uuid description: ID of the seal participant slot to update swap_to_seal_id: type: string format: uuid description: ID of the new organization seal to assign to the slot 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 create-file-field: summary: Create file upload field value: field: type: file position: x: 100 y: 300 width: 200 height: 40 page_number: 1 required: true format_rules: acceptedFileTypes: image_and_pdf 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 - 'null' 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': description: Signing request or seal participant not found content: application/json: schema: $ref: '#/components/schemas/Error' examples: not_found: value: error: Signing request not found code: NOT_FOUND seal_not_found: value: error: Organization seal not found or unavailable in this workspace code: NOT_FOUND '429': $ref: '#/components/responses/RateLimitError' operationId: patchSigningRequest x-participant-order-contract: membership: Signer and Approver recipients plus organization seal participants share one contiguous 1-based order space. CC recipients use a separate sequence and never consume a participant position. patch: 'On an unsent document, order must be in [1..n] for a move and [1..n+1] for a create. A move is shift-insert: every participant between the old and new positions is renumbered. A create with omitted order appends. Explicit order 0 is invalid.' lockedStates: A sent request accepts no membership or order change and returns SIGNING_ORDER_LOCKED_SENT. On an aborted-send request, an applied participant can narrow the reachable interval and an invalid move returns SIGNING_ORDER_LOCKED_APPLIED. create: When no seal is present, tied recipient order values are resolved deterministically and compacted to [1..n]. A seal-bearing create rejects a non-contiguous space or collision with INVALID_SIGNING_ORDER. When use_signing_order is false, or any recipient omits order, participant orders follow array order. sideEffects: Retrying a create after a later field write fails creates a second participant, matching the existing non-idempotent create contract. errors: - INVALID_SIGNING_ORDER - SIGNING_ORDER_LOCKED_SENT - SIGNING_ORDER_LOCKED_APPLIED - PARTICIPANTS_CHANGED x-codeSamples: - lang: TypeScript label: '@firma-dev/sdk' source: "import { FirmaClient } from \"@firma-dev/sdk\";\n\nconst firma = new FirmaClient({ apiKey: \"YOUR_API_KEY\" });\n\nconst response = await firma.signingRequests.patchSigningRequest({\n id: \"id\",\n body: {\n name: \"Updated Contract Name\",\n expiration_hours: 72\n }\n});\nconsole.log(response);" 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. **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: $ref: '#/components/schemas/SigningRequestUpdateResponse' '400': description: Validation errors. All section errors returned together. content: application/json: schema: $ref: '#/components/schemas/SigningRequestUpdateError' 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' operationId: updateSigningRequest x-participant-order-contract: membership: Signer and Approver recipients plus organization seal participants share one contiguous 1-based order space. CC recipients use a separate sequence and never consume a participant position. patch: 'On an unsent document, order must be in [1..n] for a move and [1..n+1] for a create. A move is shift-insert: every participant between the old and new positions is renumbered. A create with omitted order appends. Explicit order 0 is invalid.' lockedStates: A sent request accepts no membership or order change and returns SIGNING_ORDER_LOCKED_SENT. On an aborted-send request, an applied participant can narrow the reachable interval and an invalid move returns SIGNING_ORDER_LOCKED_APPLIED. create: When no seal is present, tied recipient order values are resolved deterministically and compacted to [1..n]. A seal-bearing create rejects a non-contiguous space or collision with INVALID_SIGNING_ORDER. When use_signing_order is false, or any recipient omits order, participant orders follow array order. sideEffects: Retrying a create after a later field write fails creates a second participant, matching the existing non-idempotent create contract. errors: - INVALID_SIGNING_ORDER - SIGNING_ORDER_LOCKED_SENT - SIGNING_ORDER_LOCKED_APPLIED - PARTICIPANTS_CHANGED x-codeSamples: - lang: TypeScript label: '@firma-dev/sdk' source: "import { FirmaClient } from \"@firma-dev/sdk\";\n\nconst firma = new FirmaClient({ apiKey: \"YOUR_API_KEY\" });\n\nconst response = await firma.signingRequests.updateSigningRequest({\n id: \"id\",\n signing_request_properties: {\n name: \"Updated Contract Name\",\n expiration_hours: 72\n },\n recipients: [{\n id: \"rec1-e89b-12d3-a456-426614174000\",\n first_name: \"John\",\n last_name: \"Smith\",\n email: \"john.smith@example.com\",\n designation: \"Signer\",\n order: 1\n }, {\n first_name: \"Jane\",\n last_name: \"Doe\",\n email: \"jane@example.com\",\n designation: \"Signer\",\n order: 2\n }],\n deleted_recipients: [{\n recipient_id: \"rec2-e89b-12d3-a456-426614174000\",\n field_action: \"reassign\",\n reassign_to_recipient_id: \"rec1-e89b-12d3-a456-426614174000\"\n }],\n fields: [{\n id: \"field1-e89b-12d3-a456-426614174000\",\n type: \"signature\",\n position: {\n x: 15,\n y: 85,\n width: 30,\n height: 10\n },\n page_number: 1,\n required: true,\n recipient_id: \"rec1-e89b-12d3-a456-426614174000\"\n }],\n reminders: [{\n hours: 48,\n all_users: true,\n subject: \"Reminder: Please sign the document\",\n message: \"This is a reminder to complete your signature.\"\n }]\n});\nconsole.log(response);" delete: summary: Delete a signing request description: Deletes an unsent (draft) signing request. Only signing requests that have not been sent can be deleted. For sent signing requests, use the cancel endpoint instead. tags: - Signing Requests security: - ApiKeyAuth: [] parameters: - name: id in: path required: true schema: type: string format: uuid description: Signing request ID responses: '200': description: Signing request deleted 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/SigningRequestDeleteResponse' example: message: Signing request deleted successfully signing_request_id: 550e8400-e29b-41d4-a716-446655440000 deleted_on: '2026-05-30T10:00:00.000Z' '401': $ref: '#/components/responses/UnauthorizedError' '404': $ref: '#/components/responses/NotFoundError' '409': description: Cannot delete a signing request that has been sent content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Cannot delete a signing request that has been sent. Use cancel instead. code: ALREADY_SENT '429': $ref: '#/components/responses/RateLimitError' operationId: deleteSigningRequest x-codeSamples: - lang: TypeScript label: '@firma-dev/sdk' source: "import { FirmaClient } from \"@firma-dev/sdk\";\n\nconst firma = new FirmaClient({ apiKey: \"YOUR_API_KEY\" });\n\nconst response = await firma.signingRequests.deleteSigningRequest({\n id: \"id\"\n});\nconsole.log(response);" /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: $ref: '#/components/schemas/SigningRequestUserListResponse' 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' operationId: listSigningRequestUsers x-codeSamples: - lang: TypeScript label: '@firma-dev/sdk' source: "import { FirmaClient } from \"@firma-dev/sdk\";\n\nconst firma = new FirmaClient({ apiKey: \"YOUR_API_KEY\" });\n\nconst response = await firma.signingRequests.listSigningRequestUsers({\n id: \"id\"\n});\nconsole.log(response);" /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: $ref: '#/components/schemas/SigningRequestFieldListResponse' example: results: - id: field789-e89b-12d3-a456-426614174000 type: signature recipient_id: user456-e89b-12d3-a456-426614174000 required: true read_only: false value: data:image/png;base64,iVBOR... position: x: 100.5 y: 200.75 width: 200 height: 50 page_number: 1 variable_name: null variable_defined_name: null companies_workspaces_signing_requests_id: sr123-e89b-12d3-a456-426614174000 companies_workspaces_signing_requests_users_id: user456-e89b-12d3-a456-426614174000 field_type: signature x_postion: 100.5 y_position: 200.75 width: 200 heigh: 50 final_value: data:image/png;base64,iVBOR... deleted: 0 - id: field012-e89b-12d3-a456-426614174000 type: text recipient_id: user456-e89b-12d3-a456-426614174000 required: true read_only: false value: Alice Johnson position: x: 150 y: 300 width: 250 height: 30 page_number: 1 variable_name: full_name variable_defined_name: null companies_workspaces_signing_requests_id: sr123-e89b-12d3-a456-426614174000 companies_workspaces_signing_requests_users_id: user456-e89b-12d3-a456-426614174000 field_type: text x_postion: 150 y_position: 300 width: 250 heigh: 30 final_value: Alice Johnson deleted: 0 '401': $ref: '#/components/responses/UnauthorizedError' '404': $ref: '#/components/responses/NotFoundError' '429': $ref: '#/components/responses/RateLimitError' operationId: listSigningRequestFields x-codeSamples: - lang: TypeScript label: '@firma-dev/sdk' source: "import { FirmaClient } from \"@firma-dev/sdk\";\n\nconst firma = new FirmaClient({ apiKey: \"YOUR_API_KEY\" });\n\nconst response = await firma.signingRequests.listSigningRequestFields({\n id: \"id\"\n});\nconsole.log(response);" /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' operationId: listSigningRequestReminders x-codeSamples: - lang: TypeScript label: '@firma-dev/sdk' source: "import { FirmaClient } from \"@firma-dev/sdk\";\n\nconst firma = new FirmaClient({ apiKey: \"YOUR_API_KEY\" });\n\nconst response = await firma.signingRequests.listSigningRequestReminders({\n id: \"id\"\n});\nconsole.log(response);" /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: $ref: '#/components/schemas/AuditTrailListResponse' '401': $ref: '#/components/responses/UnauthorizedError' '404': $ref: '#/components/responses/NotFoundError' '429': $ref: '#/components/responses/RateLimitError' operationId: listSigningRequestAuditTrail x-codeSamples: - lang: TypeScript label: '@firma-dev/sdk' source: "import { FirmaClient } from \"@firma-dev/sdk\";\n\nconst firma = new FirmaClient({ apiKey: \"YOUR_API_KEY\" });\n\nconst response = await firma.signingRequests.listSigningRequestAuditTrail({\n id: \"id\"\n});\nconsole.log(response);" /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' operationId: sendSigningRequest x-codeSamples: - lang: TypeScript label: '@firma-dev/sdk' source: "import { FirmaClient } from \"@firma-dev/sdk\";\n\nconst firma = new FirmaClient({ apiKey: \"YOUR_API_KEY\" });\n\nconst response = await firma.signingRequests.sendSigningRequest({\n id: \"id\"\n});\nconsole.log(response);" /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: $ref: '#/components/schemas/CancelSigningRequestResponse' '401': $ref: '#/components/responses/UnauthorizedError' '404': $ref: '#/components/responses/NotFoundError' '409': description: Cannot cancel (already cancelled, finished, or not sent) content: application/json: schema: $ref: '#/components/schemas/Error' '429': $ref: '#/components/responses/RateLimitError' operationId: cancelSigningRequest x-codeSamples: - lang: TypeScript label: '@firma-dev/sdk' source: "import { FirmaClient } from \"@firma-dev/sdk\";\n\nconst firma = new FirmaClient({ apiKey: \"YOUR_API_KEY\" });\n\nconst response = await firma.signingRequests.cancelSigningRequest({\n id: \"id\",\n reason: \"No longer needed\",\n notify_signers: true\n});\nconsole.log(response);" /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: $ref: '#/components/schemas/ResendSigningRequestResponse' '400': $ref: '#/components/responses/ValidationError' '401': $ref: '#/components/responses/UnauthorizedError' '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: $ref: '#/components/schemas/ResendConflictError' '429': $ref: '#/components/responses/RateLimitError' operationId: resendSigningRequest x-codeSamples: - lang: TypeScript label: '@firma-dev/sdk' source: "import { FirmaClient } from \"@firma-dev/sdk\";\n\nconst firma = new FirmaClient({ apiKey: \"YOUR_API_KEY\" });\n\nconst response = await firma.signingRequests.resendSigningRequest({\n id: \"id\",\n recipient_ids: [\"123e4567-e89b-12d3-a456-426614174000\"],\n custom_message: \"Gentle reminder to complete your signature\"\n});\nconsole.log(response);" /signing-requests/{id}/download: get: summary: Download Signing Request Document description: 'Retrieve a download URL for a signing request''s signed document. For completed signing requests, returns the final signed PDF. For in-progress signing requests where partial download is enabled, returns a URL to the partially-signed document generated at the time of the last signer''s completion. **Partial downloads:** Partial downloads are only available when the signing request has `allow_partial_download` enabled in settings. If the document has not been partially generated yet, a `503` is returned — retry after the `Retry-After` interval. **URL expiry:** The `download_url` is a pre-signed URL that expires. The expiry timestamp is provided in `expires_at`.' tags: - Signing Requests security: - ApiKeyAuth: [] parameters: - name: id in: path required: true description: Signing request ID schema: type: string format: uuid responses: '200': description: Download URL 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/SigningRequestDownloadResponse' '401': $ref: '#/components/responses/UnauthorizedError' '404': description: Signing request not found. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: not_found '409': description: Signing request has not been sent yet. Download is only available after the request has been sent. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: no_document_available message: Signing request has not been sent yet '429': $ref: '#/components/responses/RateLimitError' '503': description: Document generation is in progress. Retry after the indicated interval. headers: Retry-After: schema: type: integer description: Seconds to wait before retrying content: application/json: schema: $ref: '#/components/schemas/Error' examples: generation_timeout: summary: Document generation timed out value: error: generation_timeout stale_at_publication: summary: Document was stale at publication time value: error: stale_at_publication operationId: downloadSigningRequest x-codeSamples: - lang: TypeScript label: '@firma-dev/sdk' source: "import { FirmaClient } from \"@firma-dev/sdk\";\n\nconst firma = new FirmaClient({ apiKey: \"YOUR_API_KEY\" });\n\nconst response = await firma.signingRequests.downloadSigningRequest({\n id: \"id\"\n});\nconsole.log(response);" /signing-requests/{id}/signers/{signer_id}/signature: get: operationId: retrieveSignerSignature summary: Retrieve Signer Signature Image description: Retrieve a signer's adopted signature as a base64 PNG data URI, separate from the signed PDF. A signer adopts one signature applied to all their signature fields, so no field_id is needed. Drawn signatures return the captured image; typed signatures are rendered to PNG server-side. The `image` is a `data:image/png;base64,...` URI usable directly in an ``. By default a signer-ID frame is overlaid (`include_frame=false` to omit). Every successful retrieval is audit-logged. Rate limited to 60/min. Legal validity rests on the sealed PDF and completion certificate, not this image. tags: - Signing Requests security: - ApiKeyAuth: [] parameters: - name: id in: path required: true description: Signing request ID schema: type: string format: uuid - name: signer_id in: path required: true description: Signer (recipient) ID — the recipient_id from GET /fields schema: type: string format: uuid - name: include_frame in: query required: false description: Overlay the signer-ID frame on the image (default true). Set to false for the bare mark. schema: type: boolean default: true responses: '200': description: The signer's mark as a base64 PNG data URI. content: application/json: schema: type: object properties: signer_id: type: string format: uuid kind: type: string enum: - signature - initials - stamp format: type: string example: png framed: type: boolean description: Whether the signer-ID frame was overlaid. image: type: string description: PNG as a data URI. example: data:image/png;base64,iVBORw0KGgo... '401': description: Missing or invalid API key. content: application/json: schema: type: object properties: error: type: string code: type: string '404': description: Signing request/signer/field not found or not in your workspace (NOT_FOUND), or no mark captured (SIGNATURE_NOT_AVAILABLE). content: application/json: schema: type: object properties: error: type: string code: type: string '429': description: Rate limit exceeded (60/min for signature retrieval). content: application/json: schema: type: object properties: error: type: string code: type: string '500': description: Rendering failed (RENDER_FAILED) or the required access-audit write failed (AUDIT_WRITE_FAILED); no image is returned. content: application/json: schema: type: object properties: error: type: string code: type: string x-codeSamples: - lang: TypeScript label: '@firma-dev/sdk' source: "import { FirmaClient } from \"@firma-dev/sdk\";\n\nconst firma = new FirmaClient({ apiKey: \"YOUR_API_KEY\" });\n\nconst response = await firma.signingRequests.retrieveSignerSignature({\n id: \"id\",\n signer_id: \"signer_id\"\n});\nconsole.log(response);" /signing-requests/{id}/signers/{signer_id}/initials: get: operationId: retrieveSignerInitials summary: Retrieve Signer Initials Image description: Retrieve a signer's adopted initials as a base64 PNG data URI. One initials mark per signer (no field_id). Same response shape, framing, audit, and rate limit as the signature endpoint. tags: - Signing Requests security: - ApiKeyAuth: [] parameters: - name: id in: path required: true description: Signing request ID schema: type: string format: uuid - name: signer_id in: path required: true description: Signer (recipient) ID schema: type: string format: uuid - name: include_frame in: query required: false description: Overlay the signer-ID frame on the image (default true). Set to false for the bare mark. schema: type: boolean default: true responses: '200': description: The signer's mark as a base64 PNG data URI. content: application/json: schema: type: object properties: signer_id: type: string format: uuid kind: type: string enum: - signature - initials - stamp format: type: string example: png framed: type: boolean description: Whether the signer-ID frame was overlaid. image: type: string description: PNG as a data URI. example: data:image/png;base64,iVBORw0KGgo... '401': description: Missing or invalid API key. content: application/json: schema: type: object properties: error: type: string code: type: string '404': description: Signing request/signer/field not found or not in your workspace (NOT_FOUND), or no mark captured (SIGNATURE_NOT_AVAILABLE). content: application/json: schema: type: object properties: error: type: string code: type: string '429': description: Rate limit exceeded (60/min for signature retrieval). content: application/json: schema: type: object properties: error: type: string code: type: string '500': description: Rendering failed (RENDER_FAILED) or the required access-audit write failed (AUDIT_WRITE_FAILED); no image is returned. content: application/json: schema: type: object properties: error: type: string code: type: string x-codeSamples: - lang: TypeScript label: '@firma-dev/sdk' source: "import { FirmaClient } from \"@firma-dev/sdk\";\n\nconst firma = new FirmaClient({ apiKey: \"YOUR_API_KEY\" });\n\nconst response = await firma.signingRequests.retrieveSignerInitials({\n id: \"id\",\n signer_id: \"signer_id\"\n});\nconsole.log(response);" /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}: get: operationId: retrieveSignerStamp summary: Retrieve Signer Stamp Image description: Retrieve a signer's stamp for a specific stamp field as a base64 PNG data URI. Stamps are per-field, so `field_id` is required (obtain it from GET /signing-requests/{id}/fields, filtering type=stamp). Same framing, audit, and 60/min limit. tags: - Signing Requests security: - ApiKeyAuth: [] parameters: - name: id in: path required: true description: Signing request ID schema: type: string format: uuid - name: signer_id in: path required: true description: Signer (recipient) ID schema: type: string format: uuid - name: field_id in: path required: true description: Stamp field ID schema: type: string format: uuid - name: include_frame in: query required: false description: Overlay the signer-ID frame on the image (default true). Set to false for the bare mark. schema: type: boolean default: true responses: '200': description: The signer's mark as a base64 PNG data URI. content: application/json: schema: type: object properties: signer_id: type: string format: uuid kind: type: string enum: - signature - initials - stamp format: type: string example: png framed: type: boolean description: Whether the signer-ID frame was overlaid. image: type: string description: PNG as a data URI. example: data:image/png;base64,iVBORw0KGgo... '400': description: Field is not the expected type (INVALID_FIELD_TYPE). content: application/json: schema: type: object properties: error: type: string code: type: string '401': description: Missing or invalid API key. content: application/json: schema: type: object properties: error: type: string code: type: string '404': description: Signing request/signer/field not found or not in your workspace (NOT_FOUND), or no mark captured (SIGNATURE_NOT_AVAILABLE). content: application/json: schema: type: object properties: error: type: string code: type: string '429': description: Rate limit exceeded (60/min for signature retrieval). content: application/json: schema: type: object properties: error: type: string code: type: string '500': description: Rendering failed (RENDER_FAILED) or the required access-audit write failed (AUDIT_WRITE_FAILED); no image is returned. content: application/json: schema: type: object properties: error: type: string code: type: string x-codeSamples: - lang: TypeScript label: '@firma-dev/sdk' source: "import { FirmaClient } from \"@firma-dev/sdk\";\n\nconst firma = new FirmaClient({ apiKey: \"YOUR_API_KEY\" });\n\nconst response = await firma.signingRequests.retrieveSignerStamp({\n id: \"id\",\n signer_id: \"signer_id\",\n field_id: \"field_id\"\n});\nconsole.log(response);" /signing-requests/{id}/signers/{signer_id}/files/{field_id}: get: operationId: retrieveSignerFile summary: Retrieve Signer-Uploaded File description: Retrieve a file a signer uploaded to a file field. Returns a short-lived (300s) pre-signed download URL, not the bytes. `field_id` is required (from GET /signing-requests/{id}/fields, filtering type=file). Every retrieval is audit-logged; 60/min limit. Download promptly server-side before the URL expires. tags: - Signing Requests security: - ApiKeyAuth: [] parameters: - name: id in: path required: true description: Signing request ID schema: type: string format: uuid - name: signer_id in: path required: true description: Signer (recipient) ID schema: type: string format: uuid - name: field_id in: path required: true description: File field ID schema: type: string format: uuid responses: '200': description: A short-lived pre-signed URL for the signer-uploaded file. content: application/json: schema: type: object properties: signer_id: type: string format: uuid kind: type: string example: file file_name: type: - string - 'null' file_type: type: - string - 'null' file_size: type: - integer - 'null' url: type: string description: Pre-signed download URL. expires_in: type: integer example: 300 description: Seconds until the URL expires. '400': description: Field is not a file field (INVALID_FIELD_TYPE). content: application/json: schema: type: object properties: error: type: string code: type: string '401': description: Missing or invalid API key. content: application/json: schema: type: object properties: error: type: string code: type: string '404': description: Not found / not in your workspace (NOT_FOUND) or no file uploaded (SIGNATURE_NOT_AVAILABLE). content: application/json: schema: type: object properties: error: type: string code: type: string '429': description: Rate limit exceeded (60/min). content: application/json: schema: type: object properties: error: type: string code: type: string '500': description: The signed-URL generation failed (INTERNAL_ERROR) or the required access-audit write failed (AUDIT_WRITE_FAILED); no URL is returned. content: application/json: schema: type: object properties: error: type: string code: type: string x-codeSamples: - lang: TypeScript label: '@firma-dev/sdk' source: "import { FirmaClient } from \"@firma-dev/sdk\";\n\nconst firma = new FirmaClient({ apiKey: \"YOUR_API_KEY\" });\n\nconst response = await firma.signingRequests.retrieveSignerFile({\n id: \"id\",\n signer_id: \"signer_id\",\n field_id: \"field_id\"\n});\nconsole.log(response);" /documents: post: summary: Upload a document description: Request a presigned upload URL for a document. Upload the file directly to the returned URL, then pass the document_id when creating a signing request. Use this for documents larger than 5MB that exceed the inline base64 request size limit. tags: - Signing Requests security: - ApiKeyAuth: [] operationId: uploadDocument requestBody: required: true content: application/json: schema: type: object required: - file_name - file_size - content_type properties: file_name: type: string maxLength: 255 description: Name of the document file example: contract.pdf file_size: type: integer minimum: 1 maximum: 52428800 description: File size in bytes. Maximum 50MB (52,428,800 bytes). example: 15000000 content_type: type: string enum: - application/pdf - application/vnd.openxmlformats-officedocument.wordprocessingml.document description: MIME type of the document example: application/pdf responses: '201': description: Upload URL created content: application/json: schema: type: object properties: document_id: type: string format: uuid description: Document ID to pass in the signing request upload_url: type: string format: uri description: Presigned URL to PUT the document file to. Send the raw file bytes with Content-Type matching the requested content_type. upload_token: type: string description: Upload authentication token (included in the upload_url) expires_in: type: integer description: Seconds until the upload URL expires example: 3600 '400': description: Validation error (invalid file_size, content_type, etc.) '401': description: Invalid or missing API key x-codeSamples: - lang: TypeScript label: '@firma-dev/sdk' source: "import { FirmaClient } from \"@firma-dev/sdk\";\n\nconst firma = new FirmaClient({ apiKey: \"YOUR_API_KEY\" });\n\nconst response = await firma.signingRequests.uploadDocument({\n file_name: \"contract.pdf\",\n file_size: 15000000,\n content_type: \"application/pdf\"\n});\nconsole.log(response);" /signing-requests/{id}/seal-participants/{participant_id}: delete: summary: Remove a seal participant from an unsent signing request description: Remove a seal participant and the fields it owns from a signing request that has not been sent yet. After send, a seal participant can only be swapped (while paused) or the request cancelled. tags: - Signing Requests operationId: deleteSealParticipant security: - ApiKeyAuth: [] parameters: - name: id in: path required: true schema: type: string format: uuid description: Signing request ID - name: participant_id in: path required: true schema: type: string format: uuid description: Seal participant ID responses: '200': description: Seal participant removed successfully content: application/json: schema: type: object properties: success: type: boolean '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/NotFoundError' '409': description: The participant set changed, the request was sent, or an applied participant prevents compaction. content: application/json: schema: $ref: '#/components/schemas/Error' examples: sent: value: error: The signing order is locked after send code: SIGNING_ORDER_LOCKED_SENT applied: value: error: An applied participant cannot be moved code: SIGNING_ORDER_LOCKED_APPLIED changed: value: error: Participants changed since they were loaded code: PARTICIPANTS_CHANGED '429': $ref: '#/components/responses/RateLimitError' x-participant-order-contract: membership: Signer and Approver recipients plus organization seal participants share one contiguous 1-based order space. CC recipients use a separate sequence and never consume a participant position. patch: 'On an unsent document, order must be in [1..n] for a move and [1..n+1] for a create. A move is shift-insert: every participant between the old and new positions is renumbered. A create with omitted order appends. Explicit order 0 is invalid.' lockedStates: A sent request accepts no membership or order change and returns SIGNING_ORDER_LOCKED_SENT. On an aborted-send request, an applied participant can narrow the reachable interval and an invalid move returns SIGNING_ORDER_LOCKED_APPLIED. create: When no seal is present, tied recipient order values are resolved deterministically and compacted to [1..n]. A seal-bearing create rejects a non-contiguous space or collision with INVALID_SIGNING_ORDER. When use_signing_order is false, or any recipient omits order, participant orders follow array order. sideEffects: Retrying a create after a later field write fails creates a second participant, matching the existing non-idempotent create contract. errors: - INVALID_SIGNING_ORDER - SIGNING_ORDER_LOCKED_SENT - SIGNING_ORDER_LOCKED_APPLIED - PARTICIPANTS_CHANGED components: responses: 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 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 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 schemas: SealParticipantInput: type: object required: - seal_id - order description: Seal participant assignment for a signing request or template. properties: seal_id: type: string format: uuid description: ID of the organization seal to apply order: type: integer minimum: 1 description: Position in the signing sequence temp_id: type: string description: Temporary ID for referencing in field assignments within the same request CreateAndSendValidationError: type: object properties: error: type: string code: type: string description: Machine-readable error code example: VALIDATION_ERROR 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 errors: type: array description: All validation errors when multiple failures are reported together. The top-level error repeats the first item for backward compatibility. items: type: object required: - message properties: message: type: string description: Validation error during create-and-send required: - error - code AnchorTag: type: object additionalProperties: false required: - anchor_string - type - recipient_id description: Anchor tag definition for automatic field placement. Anchor tags are text markers embedded in a PDF document (e.g., '{{SIGN_HERE}}') that are automatically located and converted into positioned fields. The anchor text is removed from the PDF after processing by default. properties: anchor_string: type: string minLength: 1 maxLength: 200 description: Text string to search for in the PDF document. Common patterns include '{{SIGN_HERE}}', '{{DATE}}', etc. example: '{{SIGN_HERE}}' type: type: string enum: - signature - initial - initials - text - date - checkbox - radio_buttons - radio - dropdown - textarea - text_area - url - approval_signature - approval_checkmark - approval_date description: Type of field to place at the anchor location recipient_id: oneOf: - type: integer - type: string description: ID of the recipient assigned to this field. Use temporary ID (e.g., 'temp_1') for document-based creation or integer order for template-based. example: temp_1 x_offset: type: number description: 'Horizontal offset from anchor position. Units determined by offset_units (default: percent of page width).' default: 0 y_offset: type: number description: 'Vertical offset from anchor position. Units determined by offset_units (default: percent of page height).' default: 0 offset_units: type: string enum: - percent - pixels default: percent description: Unit type for x_offset and y_offset. 'percent' = percentage of page dimensions, 'pixels' = PDF points (72 DPI). width: type: number description: Field width as percentage of page width. Defaults vary by field type (e.g., signature=25, text=20, checkbox=3). exclusiveMinimum: 0 height: type: number description: Field height as percentage of page height. Defaults vary by field type (e.g., signature=5, text=3, checkbox=3). exclusiveMinimum: 0 case_sensitive: type: boolean default: false description: Whether anchor string matching is case-sensitive match_whole_word: type: boolean default: true description: Whether to match whole words only (bounded by non-word characters) ignore_if_not_present: type: boolean default: false description: If true, skip this anchor without error when not found in the document. If false (default), a missing anchor causes a validation error. occurrence: type: integer minimum: 0 maximum: 1000 default: 0 description: Which occurrence to place a field on. 0 = all occurrences (default), 1 = first only, 2 = second only, etc. remove_anchor_text: type: boolean default: true description: Whether to remove the anchor text using corrected glyph geometry and sub-pixel text removal. Defaults to true. add_white_background: type: boolean default: false description: Whether to draw a white background across the full resolved field rectangle. This is independent of anchor-text removal. required: type: boolean default: true description: Whether the field must be completed by the signer read_only: type: boolean default: false description: Whether the field is read-only (pre-filled) read_only_value: type: - string - 'null' maxLength: 10000 description: Static value for read-only fields variable_name: type: - string - 'null' maxLength: 255 description: Variable name for the field variable_defined_name: type: - string - 'null' maxLength: 100 description: Human-readable custom field definition name. Can be used as an alternative to variable_name for targeting fields in template-based creation. background_color: type: - string - 'null' pattern: ^#([0-9A-Fa-f]{3}|[0-9A-Fa-f]{6})$ description: Background color as hex (e.g., '#FFFDE7') example: '#FFFDE7' font_size: type: integer minimum: 8 maximum: 48 description: Optional starting/maximum font size in pixels for text-bearing field types, stored on the resolved field as format_rules.fontSize (see TextFormatRules). Text still auto-shrinks to fit the field box. Omit for automatic sizing. Values outside 8-48 are clamped; non-numeric values are ignored. example: 12 dropdown_options: description: Options for dropdown fields oneOf: - type: array items: type: string - type: object date_default: type: - string - 'null' maxLength: 50 description: Default date value date_signing_default: type: boolean default: false description: Use signing date as default multi_group_id: type: - string - 'null' maxLength: 255 description: Group ID for linking checkbox/radio fields 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' completion_title: type: - string - 'null' description: Heading shown on the completion page after signing. Null or an empty string clears the override. maxLength: 200 completion_message: type: - string - 'null' description: Body text shown on the completion page after signing. Null or an empty string clears the override. maxLength: 1000 completion_redirect_url: type: - string - 'null' format: uri description: URL the signer is redirected to from the completion page. Must use https:// (http://localhost and http://127.0.0.1 are also accepted on test-mode signing requests). Null or an empty string clears the override. maxLength: 2000 completion_redirect_delay: type: - integer - 'null' description: Seconds the completion page waits before redirecting (0 redirects immediately). Only applies when a redirect URL resolves; the page falls back to 5 seconds when no level sets a delay. Null clears the override. minimum: 0 maximum: 30 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. An existing recipient cannot be changed between CC and Signer/Approver (400); delete it and create it again. 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 language: type: - string - 'null' enum: - en - es - it - pt - fr - de - el - ru - pl - cs - sv - nl - ro - nb - ca description: Opt-in email language for this signing request. When set, all signer-facing emails (and their date formatting) use it. Omit or null to fall back to the workspace, then company, default language (unchanged behavior). SealParticipant: type: object description: Seal participant on a signing request or template. properties: id: type: string format: uuid organization_seals_id: type: string format: uuid order: type: integer minimum: 1 deleted: type: integer enum: - 0 - 1 created_at: type: string format: date-time updated_at: type: string format: date-time SigningRequestListResponse: type: object description: Paginated list of signing requests properties: results: type: array items: $ref: '#/components/schemas/SigningRequestListItem' pagination: $ref: '#/components/schemas/Pagination' required: - results - pagination 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 type: type: string enum: - text - signature - date - checkbox - initial - dropdown - radio_buttons - text_area - url - file - stamp - approval_signature - approval_checkmark - approval_date description: Type of the field. Clean alias for field_type. recipient_id: type: - string - 'null' format: uuid description: ID of the recipient assigned to this field. Clean alias for companies_workspaces_signing_requests_users_id. value: type: - string - 'null' description: Final signed value of the field. Clean alias for final_value. position: type: object description: Position and dimensions of the field on the document. All values are percentages (0-100). properties: x: type: - number - 'null' description: X position (percentage, 0-100). Clean alias for x_postion. y: type: - number - 'null' description: Y position (percentage, 0-100). Clean alias for y_position. width: type: - number - 'null' description: Width (percentage, 0-100). height: type: - number - 'null' description: Height (percentage, 0-100). Clean alias for heigh. companies_workspaces_signing_requests_id: type: string format: uuid description: 'Deprecated: redundant with path parameter. ID of the signing request this field belongs to.' companies_workspaces_signing_requests_users_id: type: - string - 'null' format: uuid description: 'Deprecated: use ''recipient_id'' instead. ID of the recipient assigned to this field.' field_type: type: string enum: - text - signature - date - checkbox - initial - dropdown - radio_buttons - text_area - url - file - stamp - approval_signature - approval_checkmark - approval_date description: 'Deprecated: use ''type'' instead. Type of the field.' required: type: boolean description: Whether the field is required. x_postion: type: - number - 'null' description: 'Deprecated: use ''position.x'' instead. X position (note: column name has typo).' y_position: type: - number - 'null' description: 'Deprecated: use ''position.y'' instead. Y position of the field.' width: type: - number - 'null' description: 'Deprecated: use ''position.width'' instead. Width of the field.' heigh: type: - number - 'null' description: 'Deprecated: use ''position.height'' instead. Height (note: column name has typo).' page_number: type: - integer - 'null' description: Page number where the field is located (1-indexed) tl_position: type: - number - 'null' description: Top-left corner position tr_position: type: - number - 'null' description: Top-right corner position bl_position: type: - number - 'null' description: Bottom-left corner position br_position: type: - number - 'null' description: Bottom-right corner position variable_name: type: - string - 'null' description: Variable name for prefilled data mapping variable_defined_name: type: - string - 'null' description: Human-readable field name from the custom field definition (e.g. 'artist_name'). Only present for fields linked to a custom field definition, null otherwise. final_value: type: - string - 'null' description: 'Deprecated: use ''value'' instead. Final signed value of the field.' date_default: type: - string - 'null' description: Default date value date_signing_default: type: - boolean - 'null' description: Whether to use signing date as default. format_rules: type: - object - 'null' description: Formatting rules (e.g., date format) validation_rules: type: - object - 'null' description: Validation rules for the field dropdown_options: description: Options for dropdown fields oneOf: - type: array items: type: string - type: object multi_group_id: type: - string - 'null' format: uuid 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: boolean description: Whether the field is read-only. read_only_value: type: - string - 'null' description: Static value for read-only fields background_color: type: - string - 'null' description: Background color as hex (e.g., '#FFFDE7') calculated_font_size: type: - number - 'null' description: Calculated font size for the field deleted: type: integer enum: - 0 - 1 description: 'Deprecated: internal field, will be removed in v2. Soft delete flag (0 = active, 1 = deleted).' required: - id - field_type - page_number 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 - 'null' 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 - 'null' format: date-time 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 - 'null' format: date-time 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 - 'null' format: uuid 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 - 'null' format: date-time description: When the signing request was sent finished_date: type: - string - 'null' format: date-time description: When all signatures were completed cancelled_date: type: - string - 'null' format: date-time description: When the signing request was cancelled declined_date: type: - string - 'null' format: date-time 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 - stamp - approval_signature - approval_checkmark - approval_date required: type: boolean recipient_id: type: - string - 'null' format: uuid variable_name: type: - string - 'null' variable_defined_name: type: - string - 'null' description: Human-readable field name from the custom field definition (e.g. 'artist_name'). Only present for fields linked to a custom field definition, null otherwise. position: type: object properties: x: type: number y: type: number width: type: number height: type: number value: type: - string - 'null' description: Final value of the field after signing dropdown_options: oneOf: - type: array items: type: string - type: object format_rules: $ref: '#/components/schemas/DateFormatRules' validation_rules: $ref: '#/components/schemas/FieldValidationRules' seal_participants: type: array description: Organization seal participants in the signing order. Empty when the request has no seals. items: $ref: '#/components/schemas/SealParticipant' required: - id - name - status - created_date UnprocessableEntityError: type: object properties: error: type: string example: A recipient's email address cannot receive messages. code: type: string example: RECIPIENT_EMAIL_SUPPRESSED description: Unprocessable entity error required: - error - code SigningRequestFieldListResponse: type: object description: List of signing request fields properties: results: type: array items: $ref: '#/components/schemas/SigningRequestField' required: - results 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 description: Value to compare against. Not required for is_filled/is_empty operators. FileFormatRules: type: object description: Formatting rules for file upload fields. Specifies which file types signers are allowed to upload. properties: acceptedFileTypes: type: string enum: - image_and_pdf - image - pdf default: image_and_pdf description: Accepted file types for upload. 'image_and_pdf' accepts JPG, PNG, and PDF. 'image' accepts JPG and PNG only. 'pdf' accepts PDF only. Files are validated by magic bytes, not just extension. Maximum file size is 10MB. example: acceptedFileTypes: image_and_pdf 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 - 'null' 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 CreateAndSendResponse: type: object properties: id: type: string format: uuid description: Signing request ID name: type: string description: Signing request name description: type: - string - 'null' 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 - 'null' format: uuid 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 - 'null' 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 warnings: type: array items: type: string description: Optional non-blocking warnings, including unknown anchor-tag properties during the compatibility window and anchor-processing warnings. description: Signing request created and sent required: - id - name - status InsufficientCreditsError: type: object properties: error: type: string example: Insufficient credits. Please purchase more credits to send signing requests. code: type: string example: INSUFFICIENT_CREDITS current_credits: type: integer example: 0 description: Insufficient credits error required: - error - code - current_credits Error: type: object properties: error: type: string description: Human-readable error message code: type: string description: 'Machine-readable error code Seal-related codes: SEALS_DISABLED, SEAL_ALREADY_REVOKED, SEAL_CREATION_DISABLED_EDGE, SEAL_ERASE_NOT_ELIGIBLE, SEAL_IMAGE_INVALID, SEAL_MUTATION_NOT_ALLOWED, SEAL_NOT_FOUND, SEAL_ORDER_COLLISION, SEAL_PAUSED, SEAL_SCOPE_FORBIDDEN, SEAL_UNAVAILABLE' errors: type: array description: All validation errors when multiple failures are reported together. The top-level error repeats the first item for backward compatibility. items: type: object required: - message properties: message: type: string message: type: string description: Detailed error description details: type: object description: Additional error details additionalProperties: true required: - error description: ' Organization Seal error codes: SEALS_DISABLED, SEAL_ALREADY_REVOKED, SEAL_CREATION_DISABLED_EDGE, SEAL_ERASE_NOT_ELIGIBLE, SEAL_IMAGE_INVALID, SEAL_MUTATION_NOT_ALLOWED, SEAL_NOT_FOUND, SEAL_ORDER_COLLISION, SEAL_PAUSED, SEAL_SCOPE_FORBIDDEN, SEAL_UNAVAILABLE' Field: type: object required: - type - position - page_number description: 'Field definition for signing requests. **Read-only fields**: Set read_only=true to pre-fill a field value that signers cannot edit. Use read_only_value for static text, or prefilled_data to auto-populate from recipient attributes. **Template-based field merging**: When creating from a template with fields array, use template_field_id (preferred) or variable_name (fallback) to match template fields. Only provided properties override template defaults (partial update). Fields not matched are ignored.' properties: id: type: string format: uuid description: Unique identifier (include for updates, omit for new fields) template_field_id: type: string format: uuid description: Template field ID to match for partial updates (template-based creation only). Use this to identify which template field to override. Takes precedence over variable_name for matching. type: type: string enum: - signature - text - date - checkbox - dropdown - initial - initials - text_area - textarea - image - stamp - approval_signature - approval_checkmark - approval_date description: Type of field. Accepts 'initial' or 'initials' (normalized to 'initial'), 'textarea' or 'text_area' (normalized to 'text_area'). position: type: object required: - x - y - width - height description: 'Field must fit within page bounds: x + width <= 100 and y + height <= 100' properties: x: type: number minimum: 0 maximum: 100 description: X coordinate as percentage (0-100) y: type: number minimum: 0 maximum: 100 description: Y coordinate as percentage (0-100) width: type: number minimum: 0 maximum: 100 description: Width as percentage (0-100). x + width must be <= 100 height: type: number minimum: 0 maximum: 100 description: Height as percentage (0-100). y + height must be <= 100 page_number: type: integer minimum: 1 description: Page number where field is located (1-indexed). Must not exceed the document's total page count. required: type: boolean default: false description: Whether field must be completed recipient_id: type: string description: ID of recipient assigned to this field. Use real UUID for template-based creation or updates, or temporary ID (e.g., 'temp_1') for document-based creation to reference recipients defined in the same request. variable_name: type: - string - 'null' maxLength: 100 description: Variable name for field (used in templates). Also used as fallback for field matching in template-based creation when template_field_id is not provided. variable_defined_name: type: - string - 'null' maxLength: 100 description: Human-readable custom field definition name. Can be used as an alternative to variable_name for targeting fields in template-based creation. dropdown_options: description: Options for dropdown fields oneOf: - type: array items: type: string - type: object date_default: type: - string - 'null' format: date description: Default date value date_signing_default: type: boolean default: false description: Use signing date as default multi_group_id: type: - string - 'null' format: uuid description: Group ID for linking multiple checkbox or radio button fields together. Fields sharing the same multi_group_id behave as a mutually exclusive group (like radio buttons) - selecting one automatically deselects the others in the group. Use the same UUID across multiple fields to create a group where only one option can be selected at a time. format_rules: oneOf: - $ref: '#/components/schemas/DateFormatRules' - $ref: '#/components/schemas/FileFormatRules' - type: object additionalProperties: true description: 'Formatting rules for field value. For date fields, use DateFormatRules schema with dateFormat property. For file fields, use FileFormatRules schema with acceptedFileTypes property (image_and_pdf, image, or pdf). For url fields, use { urlDisplayText: string }. Text-bearing fields (text, textarea, email, name, phone, company, title, number, dropdown, url, date) additionally accept an optional fontSize property (integer px, 8-48, clamped) - see TextFormatRules.' 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 - 'null' 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 - 'null' 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' 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' description: Conditional rules for when this field is visible. When set, the field is hidden unless the conditions evaluate to true. Hidden fields are not validated on submission. background_color: type: - string - 'null' pattern: ^#([0-9A-Fa-f]{3}|[0-9A-Fa-f]{6})$ description: Background color for the field as a hex color string (e.g., '#FFFDE7', '#fff'). Useful for highlighting fields that need attention. example: '#FFFDE7' seal_participant_temp_id: type: - string - 'null' description: Temporary ID of the seal participant this field is assigned to (matches temp_id in seal_participants array). Used during creation to link fields to seal participants defined in the same request. CancelSigningRequestResponse: type: object properties: message: type: string signing_request_id: type: string format: uuid cancelled_on: type: string format: date-time notify_signers: type: boolean emails_sent: type: integer description: Number of cancellation notification emails sent to signers description: Signing request cancellation result required: - message - signing_request_id - cancelled_on ResendSigningRequestResponse: type: object properties: message: type: string signing_request_id: type: string format: uuid recipients_notified: type: integer recipients_failed: type: integer description: Number of recipients whose resend notification failed to send recipients: type: array items: type: object properties: id: type: string format: uuid email: type: string name: type: string description: Signing request resend result required: - message - signing_request_id 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 - Approver - CC description: Role of the recipient. Signer signs the document, Approver approves with approval fields, CC receives a copy when complete. order: type: integer minimum: 1 description: Signing order finished_date: type: - string - 'null' format: date-time description: When this recipient completed signing signature_details: type: - object - 'null' description: Details about the recipient's signature SigningRequestUserListResponse: type: object description: List of signing request users properties: results: type: array items: $ref: '#/components/schemas/SigningRequestUser' required: - results FieldValidationRules: type: - object - 'null' description: Validation rules for field values. Reserved for future use - currently not enforced for any field types. additionalProperties: true SigningRequestUpdateResponse: 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 - 'null' 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 - 'null' format: date-time 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 - 'null' format: uuid description: Template ID if created from a template expires_at: type: - string - 'null' format: date-time description: ISO 8601 timestamp when the signing request expires created_date: type: string format: date-time description: Creation timestamp sent_date: type: - string - 'null' format: date-time description: When the signing request was sent finished_date: type: - string - 'null' format: date-time description: When all signatures were completed cancelled_date: type: - string - 'null' format: date-time 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) description: Signing request update result required: - id - name 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 - 'null' 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 - 'null' format: date-time 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 - 'null' format: date-time 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 - 'null' format: date-time finished_on: type: - string - 'null' format: date-time cancelled_on: type: - string - 'null' format: date-time declined_on: type: - string - 'null' format: date-time last_changed_on: type: string format: date-time last_signing_action_on: type: - string - 'null' format: date-time 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 - 'null' description: Certificate generation status information properties: generated: type: boolean description: Whether the final certificate PDF has been generated generated_on: type: - string - 'null' format: date-time 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 - 'null' format: uri description: Signed URL to download the final signed document (PDF with certificate). URL expires after 1 hour. final_document_download_error: type: - string - 'null' enum: - file_not_accessible - null document_only_download_url: type: - string - 'null' format: uri description: Signed URL to download the document-only PDF. URL expires after 1 hour. document_only_download_error: type: - string - 'null' enum: - file_not_accessible - null certificate_only_download_url: type: - string - 'null' format: uri description: Signed URL to download the certificate-only PDF. URL expires after 1 hour. certificate_only_download_error: type: - string - 'null' enum: - file_not_accessible - null seal_participants: type: array description: Organization seal participants in the signing order. Empty when the request has no seals. items: $ref: '#/components/schemas/SealParticipant' required: - id - name - status - companies_workspaces_id SigningRequestDownloadResponse: type: object properties: status: type: string enum: - finished - in_progress - cancelled - declined - expired description: Signing request status. `finished` means all signers have completed. `in_progress` means signing is still ongoing and this is a partial download. `cancelled`, `declined`, and `expired` indicate terminal states where the document is a partial snapshot from the point when signing ended. is_partial: type: boolean description: Whether this download URL points to a partially-signed document (not all signers have completed). download_url: type: string format: uri description: Pre-signed URL to download the PDF document. Expires at the time indicated by `expires_at`. generated_at: type: - string - 'null' format: date-time description: ISO 8601 timestamp when the document was last generated. For partial downloads, this is when the partial PDF was created. expires_at: type: string format: date-time description: ISO 8601 timestamp when the `download_url` expires. Fetch this endpoint again for a fresh URL after expiry. required: - status - is_partial - download_url - expires_at SigningRequestDeleteResponse: type: object properties: message: type: string signing_request_id: type: string format: uuid deleted_on: type: string format: date-time description: Signing request deletion confirmation required: - message - signing_request_id 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') SigningRequestCreateResponse: type: object description: Signing request as returned by CREATE endpoints (POST /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 - 'null' 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 - 'null' format: uuid 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 - 'null' format: date-time description: When the signing request was sent finished_date: type: - string - 'null' format: date-time description: When all signatures were completed cancelled_date: type: - string - 'null' format: date-time 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 non-blocking warnings, including unusual recipient email formats, unknown anchor-tag properties during the compatibility window, and anchor-processing warnings. seal_participants: type: array description: Organization seal participants in the signing order. Empty when the request has no seals. items: $ref: '#/components/schemas/SealParticipant' required: - id - name - status SigningRequestCreateField: type: object description: Field as returned in CREATE signing request responses (flat position, database-style) properties: id: type: string format: uuid description: Unique identifier for the field type: type: string enum: - text - signature - date - checkbox - dropdown - radio_buttons - number - text_area - file - initial - stamp - approval_signature - approval_checkmark - approval_date description: Type of the field recipient_id: type: - string - 'null' format: uuid 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 - 'null' description: Static value for read-only fields variable_name: type: - string - 'null' description: Variable name for prefilled data mapping variable_defined_name: type: - string - 'null' description: Human-readable field name from the custom field definition (e.g. 'artist_name'). Only present for fields linked to a custom field definition, null otherwise. dropdown_options: description: Options for dropdown fields oneOf: - type: array items: type: string - type: object format_rules: type: - object - 'null' description: Formatting rules (e.g., date format) validation_rules: type: - object - 'null' description: Validation rules for the field date_signing_default: type: boolean description: Whether to use signing date as default final_value: type: - string - 'null' description: Pre-filled or final value of the field required: - type - recipient_id - page_number 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 - 'null' description: Recipient first name last_name: type: - string - 'null' description: Recipient last name name: type: - string - 'null' description: Combined full name (auto-constructed from first_name + last_name) email: type: string format: email description: Recipient email address designation: type: string enum: - Signer - Approver - CC description: Role of the recipient. Signer signs the document, Approver approves with approval fields, CC receives a copy when complete. order: type: integer minimum: 1 description: Signing order phone_number: type: - string - 'null' description: Recipient phone number street_address: type: - string - 'null' description: Street address city: type: - string - 'null' description: City state_province: type: - string - 'null' description: State or province postal_code: type: - string - 'null' description: Postal code country: type: - string - 'null' description: Country title: type: - string - 'null' description: Job title company: type: - string - 'null' description: Company name custom_fields: type: - object - 'null' description: Custom key-value pairs finished_date: type: - string - 'null' format: date-time description: When this recipient completed signing required: - first_name - email - designation 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. A recipient with designation CC is never matched to a template user; it is added as a CC recipient, and the template''s CC recipients are copied to the signing request, skipping any whose email (case-insensitive) is already on a CC recipient of the request. **Temporary IDs**: For document-based creation, use temporary IDs (format: ''temp_1'', ''temp_2'', etc.) to reference recipients in fields and reminders before they''re created. **CC recipients**: CC recipients receive a completed copy but cannot sign or have fields assigned. At least one Signer is required. An existing recipient cannot be changed between CC and Signer/Approver (400); delete it and create it again.' 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. Not used for CC recipients, which are never matched to a template user. first_name: type: string maxLength: 100 description: Recipient's first name last_name: type: string maxLength: 100 description: Recipient's last name (optional, but required if using full_name or last_name prefilled variables) email: type: string format: email maxLength: 255 description: Recipient's email address designation: type: string enum: - Signer - Approver - CC description: Role of the recipient. Signer signs the document, Approver approves with approval fields, CC receives a copy when complete. order: type: integer minimum: 1 description: Signing sequence number. Recipients must sign in order, with lower numbers signing first. This field is required for all recipients. phone_number: type: - string - 'null' maxLength: 50 description: Recipient's phone number street_address: type: - string - 'null' maxLength: 255 description: Street address city: type: - string - 'null' maxLength: 100 description: City state_province: type: - string - 'null' maxLength: 100 description: State or province postal_code: type: - string - 'null' maxLength: 20 description: Postal/ZIP code country: type: - string - 'null' maxLength: 100 description: Country title: type: - string - 'null' maxLength: 100 description: Job title company: type: - string - 'null' maxLength: 255 description: Company name custom_fields: type: object additionalProperties: true description: Custom key-value pairs for additional recipient data 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 - 'null' format: uuid description: Specific user to send reminder to (used in template context) recipient_id: type: - string - 'null' format: uuid description: Specific recipient to send reminder to (used in signing request context, same as template_user_id) sent_on: type: - string - 'null' format: date-time 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 required: - id - hours - subject - message 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 - 'null' description: Recipient first name last_name: type: - string - 'null' description: Recipient last name designation: type: string enum: - Signer - Approver - CC description: Role of the recipient. Signer signs the document, Approver approves with approval fields, CC receives a copy when complete. order: type: integer minimum: 1 description: Signing order finished_on: type: - string - 'null' format: date-time description: Timestamp when this recipient completed all actions declined_on: type: - string - 'null' format: date-time description: Timestamp when this recipient declined to sign decline_reason: type: - string - 'null' description: Reason provided by recipient for declining phone_number: type: - string - 'null' description: Recipient phone number street_address: type: - string - 'null' description: Recipient street address city: type: - string - 'null' description: Recipient city state_province: type: - string - 'null' description: Recipient state or province postal_code: type: - string - 'null' description: Recipient postal code country: type: - string - 'null' description: Recipient country title: type: - string - 'null' description: Recipient job title company: type: - string - 'null' description: Recipient company name custom_fields: type: - object - 'null' 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 - 'null' description: Variable name of the read-only field variable_defined_name: type: - string - 'null' description: Human-readable field name from the custom field definition (e.g. 'artist_name'). Only present for fields linked to a custom field definition, null otherwise. 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 required: - id - first_name - email - designation - order ResendConflictError: 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 description: Resend conflict error required: - error - code 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 SigningRequestUpdateError: 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 description: Signing request update validation error required: - error Pagination: type: object properties: current_page: type: integer page_size: type: integer total_count: type: integer total_pages: type: integer description: Pagination metadata for list responses required: - current_page - page_size - total_count - total_pages 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. 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 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 fontSize: type: integer minimum: 8 maximum: 48 description: Optional starting/maximum font size in pixels for the rendered field value. Text still auto-shrinks to fit the field box. Omit for automatic sizing. Values outside 8-48 are clamped. example: dateFormat: MMMM dd, yyyy AuditTrailListResponse: type: object description: List of audit trail entries 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 - 'null' description: Who performed the action (signer name/email or admin/API key) ip_address: type: - string - 'null' description: IP address of the signer (signer events only) details: type: - object - 'null' description: Additional event-specific metadata required: - results SigningRequestSettings: type: object description: Settings returned by the signing request list and detail endpoints. Templates use the TemplateSettings schema (no identity fields). properties: allow_download: type: boolean description: Whether recipients can download the document default: true attach_pdf_on_finish: type: boolean description: Whether to attach PDF when signing is complete default: true allow_editing_before_sending: type: boolean description: Whether the signing request can be edited before sending default: false use_signing_order: type: boolean description: Whether signing order is enforced among recipients. When true, signers receive the document in sequence based on their order. When false, all signers receive the document simultaneously. default: true hand_drawn_only: type: boolean description: When enabled, signers can only hand-draw their signatures and cannot use typed/font-based signatures default: false send_signing_email: type: boolean description: Whether to send signing request notification emails to signers default: true send_finish_email: type: boolean description: Whether to send completion email when all signers finish default: true send_expiration_email: type: boolean description: Whether to send expiration notification email when request expires default: true send_cancellation_email: type: boolean description: Whether to send cancellation notification email when request is cancelled default: true require_otp_verification: type: - boolean - 'null' description: Whether signers must verify their email with a one-time code before accessing the document. null = inherit from workspace/company setting. default: null disable_guided_navigation: type: - boolean - 'null' description: Disable automatic scrolling to the next required field during signing. Inherits from workspace or company if not set. allow_presigning_download: type: - boolean - 'null' description: Allow signers to download the original document before signing. Inherits from workspace or company setting when null. show_qr_code: type: - boolean - 'null' description: Show a QR code on the signing page that lets signers continue on their phone. Inherits from workspace or company setting when null. identity_editable_fields: type: - array - 'null' items: type: string description: Identity fields signers may edit before signing (e.g. ["name", "company"]). null = disabled. When set, a confirmation dialog lets signers edit the specified fields. notify_identity_change_email: type: boolean default: false description: Send an email notification when a signer changes their identity. requestBodies: 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. 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.